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Introduction 


CP/68 is a floppy-disc-based operating system that supports standard 
peripherals such as a line printer, CRT console, paper-tape reader and 
punch, and auxiliary consoles. The preliminary specification was 
described in EDN's Software Systems Design Course (Chapter 7), November 
20, 1978. The current version of CP/68 is based on that specification and 
an improvement on it. 

The operating system’s modularity makes it easy to manage 
conceptually, and a pleasure to use. It is the most powerful system 
available for the 6800 family of microprocessors. 

This book presents the entire operating system in seven distinct 
parts. Part I introduces you to the operation of the program; Part II 
adds the Advanced User's Guide; Part III covers the system's operation in 
detail; Part 4 explores the operation of the formatting utility; Part 5 
introduces the random-access file support; Part 6 provides the 
information you will need to adapt the software to nonstandard hardware 
configurations; Part 7 gives complete source listings. 
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PART 1 


CP/68 GENERAL INFORMATION 


COMMAND STRUCTURE 


CP/68 commands consist of a command name and optional parameters. Some 
commands are memory resident and will execute immediately; others are 
transient (stored on disk) and must be loaded from disk before they are 
executed. System command names may be abbreviated to three characters; 
user-defined commands are invoked by entering their full names. These 
command files must be binary type with transfer addresses (type 01). 

Where CP/68 requires numeric values, either decimal or hexadecimal 
notation may be used. Hex values must be preceded by a dollar sign ($). 
The period (.) is used for an operator prompt. 


FILENAMES 


File names in CP/68 consist of two parts: a name and an extension. 
The name is a string of alphanumeric characters up to 8 characters in 
length. The extension consists of up to 3 alphanumeric characters. The 
first character of both the filename and extension MUST be an alpha 
character. The name is separated from its extension by a period. The 
following are valid filenames: 


INPUT.TXT 


MYFILE.B 


HI.HEX 


JACKS.FIL 


To specify a file, give the disk drive number, filename and 
extension. The drive number is given as a decimal digit followed by a 
colon. The following are examples of unique files: 


0:INPUT.TXT 1:INPUT.TXT 1:INPUT.HEX 0:INPUT2.TXT 


If the drive number is zero it may be omitted. The following identify the 
same file: 


0:BOBS.BIN B0BS.BIN 

Note that only alphanumeric characters may appear in filenames or 
extensions. The following are invalid filenames: 
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1:JACKSFILE.HEX 
2:TEMP.FILE 
0 TEST.TMP 
STBL+.BIN 
EDITOR 


(name more than 8 characters) 
(extension more than 3 characters) 
(colon missing after drive number) 
(+ is a non-alphanumeric character) 
(file extension missing) 


WILDCARD FEATURES 


CP/68 permits manipulation of classes of files. The mechanism for 
forming such classes is called wildcarding. Two wildcard characters 
perform unique identification tasks. The asterisk (*) matches an entire 
string of characters of arbitrary length. Since a complete filename 
consists of two strings, a name and an extension, the wildcard filename 
*.* is a short form of expressing all possible filenames. The wildcard 
filename *.HEX expresses all filenames with the extension HEX. 

The second wildcard character is the question mark (?). This 
character substitutes for any single character, including a blank. Hence, 
the filename TEST?.HEX is equivalent to TEST.HEX or TESTP.HEX or 
TEST2.HEX. It is not equivalent to TESTING.HEX. The filename *.* is 
equivalent to ????????.???. 

CP/68 SYSTEM COMMANDS 


ASSIGN (transient) 


This command assigns logical device names to physical devices. CP/68 
supports the following logical devices. 

CON the console terminal I/O device 

PTR paper-tape reader 

PTP paper-tape punch 

DSK disk drive 

LPT line printer 

MTA magnetic tape 

TTY teletype (could be second console with 
paper-tape facilities) 

NUL null device (bit bucket) 

ASSIGN manipulates the relationship of physical devices to logical 
device names. For instance, if it is desired to use the teletype as the 
console device, you need only enter 

ASSIGN CON=TTY 


(c) Hemenway Associates, Inc., 1979 


3 






CAUTION: Take care with assignments. It is possible to get 

into trouble. The console device should ALWAYS be a device 
capable of input. 

Now, all console messages and input will use the teletype physical 
device. Suppose, however, that one wanted to test a routine which would 
simply output characters. The following command could be used to direct 
the paper-tape punch output to the Null device: 

ASSIGN PTP=NUL 

Devices can be repeatedly ASSIGNed. The STATUS command will give the 
present state of the device assignments. 

ASSIGN C0N=LPT 

would lock up the system requiring a restart. One should not re-assign 
the DSK device, as that is where the system gets its transient commands. 

The command can make as many assignments as desired at one time. 
After each command line, it will re-prompt for another command line. 
Enter the escape character followed by a CR (see SET under ES for a 
definition of this input), to leave ASSIGN and return to the command 
level. 


BOOT (transient) 


When a fresh copy of the system file is brought into the transient area 
from the disk, the system is said to have been booted. Any file which was 
LINKed on the disk in drive zero can be BOOTed. BOOT works as a 
specialized LOAD. 


DELETE (transient) 


This command is used to remove a file from disk. Wildcard characters in 
filenames can be used to remove categories of files. DELETE can process 
multiple command lines. 

DELETE [drive:] filename.ext 

where the drive number will default to drive zero. The filename and 
extension fields may contain wildcard characters. When the named file(s) 
are found the command issues a prompt that gives the user a chance to 
save the file. 

DELETE MYFILE.TMP 

DELETE-0:MYFILE.TMP ? .YES 

The YES response assures the operating system that this is the file 
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to be deleted. The YES can be abbreviated to Y; any input other than Y is 
interpreted as a NO. 


DELETE *.TMP 

DELETE-0:MYFILE.TMP ? .NO 

would be the correct response if MYFILE.TMP was not the one that was to 
be deleted. This strategy saves you from being wiped out by typos. If 
there are several matches—due to the use of a wildcard character in the 
filename—each will be prompted in turn, and any of the matches may be 
removed. Suppose, for example, that there are three TXT files on drive 1, 
named TEST1, TEST2, and TEST3. Then the following command: 

DELETE 1:TEST?.TXT 

DELETE-1:TEST1.TXT ? .NO 

DELETE-1rTEST2.TXT ? .YES 

DELETE-1rTEST3.TXT ? .YES 

DELETE . 

This removes files TEXT2.TXT and TEXT3.TXT while leaving TEXT1.TXT . 
Enter the escape character followed by a carriage return to leave DELETE 
and return to the command level. 


DIRECTORY (resident) 


The DIRECTORY command provides a list of the files on a specified disk. 
The listing prints on the console device unless directed to the line 
printer. 

DIRECTORY (goes to console) 

DIRECTORY /L (goes to lineprinter) 

The directory listing has the following format: 

NAME TYPE ACCESS FIRST-TRACK/SECTOR LAST-TRACK/SECTOR SECTOR COUNT 

The type code, access code, track/sector, etc. are output in hexadecimal. 
The type codes defined in CP/68 are: 

00 binary file 

01 binary file with transfer address 

02 random access 

03 text file (hex file) 

The access codes defined in CP/68 are: 
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00 can be renamed or deleted 

01 can be renamed but not deleted 

02 cannot be renamed or deleted 

Filenames are listed as 8-character strings with 3-ch a racter extensions. 
Following the directory list, the total number of disk sectors used by 
the listed files is listed in decimal. 

The DIRECTORY command allows several levels of file qualification 
for listing categories of files. 

DIRECTORY [/L] [drive:] [filename.ext] 

The drive will default to disk zero. The filename and extension may use 
wildcards. For example: 


DIRECTORY 1:«.HEX 

will list on the console all files from disk 1 which have the extension 
HEX . Another example: 


DIRECTORY /L TEST?.* 

will list on the line-printer all files from disk zero which have names 
beginning with TEST followed by a character (or blank). 


EXIT (resident) 


This command causes control to shift from CP/68 to the underlying 
hardware system monitor. To get back to CP/68 either jump to the cold- 
start location or re-boot the system. 


INITIALIZE (transient) 


The INITIALIZE command formats a specified disk. All disks must be 
initialized before they can be used with CP/68. 

INITIALIZE drive number 

The drive number must be present even if the drive is zero. The command 
echoes the drive number, allowing the user to save the disk's contents. 

INITIALIZE 1 

INIT. DISK IN DRIVE 1 ? .YES 

will begin the initialization process on the disk in drive 1. The 
initialization process wipes out the entire contents of the disk. 

INITIALIZE 2 

INIT. DISK IN DRIVE 2 ? .NO 
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returns to the command level leaving the disk unchanged. Upon completion 
of the initialization process (which may take several minutes) CP/68 
returns to the command level. 


JUMP (resident) 


This command allows the user to leave CP/68 and go to any arbitrary 
absolute address. If the program at that address does a subroutine return 
(RTS instruction), CP/68 will continue at the command level. 

JUMP $E113 

will go to the address Ell3 (hexadecimal). 

JUMP 256 

will go to the address 256 (decimal). 


LINK (transient) 


This command sets the linkages for BOOT; it prompts the user for a file 
name. This file must be a binary file with transfer address (type 01). 
Once performed, the file named in LINK will be the file BOOTed when that 
disk is in drive zero. 

LINK 

ENTER SYSTEM FILE ? .CP68.SYS 

links the file CP68.SYS as the file to be bootstrapped. The drive number 
defaults to zero; no wildcard characters are permitted in the filename or 
extension. 


LOAD (resident) 


This command puts programs into the transient area. They are not 
executed; control returns to CP/68 command level. LOAD requires that 
files be binary type (00 or 01 type). 

LOAD [drive:] filename.ext 

where the drive will default to zero. No wildcard characters are 
permitted in the filename or extension. 

LOAD 1:PR0G1.BIN 

loads PR0G1.BIN into the transient area. 
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PIP (transient) 


The peripheral-interchange program (PIP) provides the operations for 
media conversion (eg, load, print, copy and combine disk files), 
referring to each peripheral device by name. 

PIP destinationsource[,source][,source]. 

where destination and source are: 

[drive:] filename.ext 
device 

Device is one one of the logical devices (see ASSIGN). 

In the case of a disk-to-disk copy, for example, 

PIP newdrive:=source drive: 

copies the contents of the source drive exactly (sector for sector) onto 
the disk in newdrive. PIP prompts the user, providing a chance to save 
the contents of the newdrive. 

PIP 0:=1: 

COPY FROM DRIVE 1 TO DRIVE 0 ? .YES 

will make the disk in drive 0 an exact copy of the disk in drive 1. A 
selective disk-to-disk copy follows a different form. 

PIP destination:=source:filename.ext 

where the filename and extension may contain wildcards. This will cause 
copies of all files on the source disk which match the filename and 
extension to be reproduced on the destination disk. All files on the 
destination disk are untouched; only those new files which were copied 
from the "source" disk will be written on the destination disk. If files 
with the same filename.ext already exist on the destination disk, an 
error indication is printed and the file is not copied. 

PIP 0:=1:*.REL 

copies all files on drive 1 that have the extension REL onto drive 0. The 
following command will copy all files from disk 0 to disk 1. 

PIP 1:=0:*.* 

This is a different form of copy from PIP 1:=0: . Using the wildcard 

filename.ext will copy the files into as sequential as possible a format 
on the new disk. Only the data sectors are copied, not the entire disk. 
Also, this form prompts the user as each file is copied, allowing very 
selective copying. 
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PIP can also transfer data between devices. For example, the 
following command can be used to view the contents of a file containing 
ASCII text: 


PIP CON=filename.ext 

Similarly, the contents of the file could be printed using PIP. 

PIP LPT=filename.ext 
PIP can be used to create text files. 

PIP filename.ext=CON 

builds a new file with the data typed at the console device. The END-FILE 
character (control-D, hex 04) is used to end the file. PIP can be used to 
transfer data from device to device as follows: 

PIP LPT=C0N (print data from console) 

PIP PTP=PTR (duplicate a paper-tape) 

PIP TTY=C0N (type from one device to another) 

and many other combinations. PIP allows the user to combine several 
sources of input into one. This can be used to append several files into 
one, as in: 


PIP bigfilerfile 1, file 2, file 3, .... 

Input from several devices can also be combined. 

PIP newfile=oldfile,CON 

lets you type new data after the oldfile is copied to the newfile. 

PIP can also perform data translations. Internal storage of programs 
is in a binary format which cannot be listed, printed or copied to ASCII- 
character devices. PIP can convert the internal binary format to a 
hexadecimal format (MIKBUG) which can be used for listing, etc. Such data 
can also be converted into binary format. The following command converts 
a MIKBUG paper-tape file into an internal hexadecimal file: 

PIP MYFILE.HEX/H=PTP 

The following command can be used to convert the hex file into an 
internal binary file: 


PIP MYFILE.BIN/B=MYFILE.HEX 

PIP can be used to punch MIKBUG format tapes as follows: 

PIP PTP/H=filename.BIN 

so that, for example, one could punch a copy of the system with the 
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command: 


PIP PTP/H=CP68.SYS 

where CP68.SYS is a binary file. PIP can also be used to list or view a 
program file as follows: 

PIP LPT/H=INIT.CMD (transient INITIALIZE ) 

PIP CON/H=CP68.SYS 

When copying a file from one disk to another, PIP maintains the filetype, 
and sets the access code to 00. It may be desirable at times to force the 
type of a file to TEXT (03). This can be done as follows: 

PIP 1:TEMP.TXT/T=C0N 

The switch /T makes 1:TEMP.TXT a text file. Otherwise, a file produced by 
PIP will default to binary type. (00) 

PIP can process multiple command lines. It will prompt the user 
after each command is completed. Enter an escape character to return to 
command level in CP/68. 


RENAME (resident) 


To change the name of a file without modifying its contents, use 

RENAME [drive:] oldname.oldext,newname.newext 

where the drive will default to zero. The file access code must be 00 or 
01 to allow renaming. The newname must not exist already with that 
extension. The following command, for example, will rename the file 
BOBS.OLD to BOBS.NEW: 


RENAME BOBS.OLD,BOBS.NEW 

No wildcard characters are permitted in either the new or old names or 
extensions. 


SAVE (resident) 


This command saves an area of memory as a binary file. 

SAVE [drive:] filename.ext,startad,endad [.transfer ad] 

where the drive defaults to zero. The filetype of the save-file will be 
00 if no transfer address is present, and 01 if a transfer address is 
supplied. For example, the following command will save the first 8k of 
memory as a system file to be entered at the address 07BC hexadecimal. 
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SAVE 1:CP68.SYS,$0000,$2000,$07BC 


Addresses can also be entered in decimal notation. To save the first 256 
bytes of memory: 


SAVE BASEPAGE.SAV,0,256 

No wildcard characters are permitted in the filename or the extension. 


SECURITY (transient) 


The files's security is determined by its access code, (see DIRECTORY). 
The code permits protection of certain files from deletion or renaming. 
SECURITY loads into the transient area. Its syntax is 

SECURITY [drive:] filename.ext ,access-code 

where the drive will default to zero. For example, to remove any 
protection from the file CP68.SYS on drive zero: 

SECURITY CP68.SYS,0 

or to protect the file INIT.CMD from deletion: 

SECURITY INIT.CMD,2 

To allow INIT.CMD to be renamed but not deleted: 

SECURITY INIT.CMD,1 

No wildcard characters are permitted in either the filename or extension. 


SET (transient) 


This command allows the user to control the characteristics of the 
console and lineprinter devices. 

SET parameter=value 

where the following parameters are defined for the console: 

BS — Backspace character. This character may be set to any ASCII 
character on the console device. Control-H (08H) is the default. 

DL ~ delete character; causes the entire line just entered to be 
deleted. Control-U (15H) is the default. 

DP — depth count. The console will be paged with DP lines per page. This 
can be used to avoid scrolling; defaults to zero which disables paging. 
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WD — Width. Sets the numbex- of characters that will appear on a line. 
The default (zero) disables the line limit. 

NL — null count. Sets the number of nonprinting null characters sent 
with each carriage return. Allows delays for mechanical terminals. The 
default is zero. 


TB — tab character. Defines the character to be decoded as a tab. 
Default is Control-I (09H). 

DX — duplex switch. Selects either full or half duplex operation for the 
console. Default is F (full); H is half duplex. 

EJ — eject count. The number of lines skipped at the end of each page. 
If the pause switch is set the system waits for an escape character 
before continuing. Defaults to zero. 

ES — escape character. Defines the escape character; default is the 
ASCII escape character (1BH). 

PS — pause switch. Determines whether or not the system will wait at the 
end of a page. Valid values are Y (yes) and N (no); default is N. 


Two parameters are exclusively for the line printer. 

LD — depth. Sets the number of lines per page; defaults to 60 decimal. 

LW — width. Sets the number of characters per line; defaults to 80 
decimal. 

With the exception of DX and PS, all parameters take a number which may 
be either decimal or hexadecimal. The following are sane valid commands: 


SET LD=50 
SET DX=H 
SET BS=$08 
SET EJ=0 
SET PS=Y 


(50 lines per page on LPT) 
(half-duplex CON) 
(backspace CNTL-H) 

(no formfeeds) 

(pause on) 


SET allows multiple command lines. It will prompt after each command 
line. Enter an escape character followed by a carriage return to return 
to command level. 


12 


(c) Hemenway Associates, Inc., 1979 



STATUS (transient) 


A systems status is its list of the present state of device assignments—— 
printed on the current console device. It returns directly to command 
level after listing the devices. See ASSIGN for a complete list of device 
names. 


SUBMIT (resident) 


This command allows the use of a file containing CP/68 command lines as a 
source of console commands. The text lines in the file are used as though 
they were typed at the console. The memory resident SUBMIT can invoke any 
other command under CP/68. The file must be a text file (type 03), built 
with either the editor or PIP. The syntax of the SUBMIT command is: 

SUBMIT [drive:] filename.ext 

where the drive defaults to zero. All commands from the file will be 
echoed as they are read. There is a special divert character used in 
SUBMIT files. This is the ampersand "& n symbol. 

The use of the divert character allows a one-line console command to 
be inserted into a SUBMIT command string. When is found in a SUBMIT 
file, the user is prompted for a command. This command is executed, and 
then the SUBMIT file is resumed. When the end of the file is encountered, 
the system returns to command level at the console. For example, suppose 
the file SUBMIT.TXT contains the following: 

DIRECTORY 1 
STATUS 

ASSIGN PTR=TTY 
(escape) 

& 

LOAD INIT.CMD 
end of file 

Then, the following command: 


SUBMIT SUBMIT.TXT 

would first list the directory of drive 1, give the device status of the 
system, assign the PTR device to the TTY, escape to command level, accept 
a user command from the console and execute it, load the file INIT.CMD, 
and return to command level. 


No wildcard characters are permitted in the filename or extension. 
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SYSTEM DEVICE ERRORS 


All device errors in CP/68 are reported in the following format: 

device-name ERROR: number 

where device-name is the three-character logical name and the error 
number is hex encoded. For example: 

LPT ERROR: OA 
DSK ERROR: 02 

are system device error messages. The set of errors defined in CP/68 are: 

01 - end of directory found in search 

02 - file already in use 

03 - file already exists 

04- no such file exists 

05- read/write error 

06- directory overflow 

07- disk full 

08- end-file encountered 

09 - bad disk sector, bad media 

0A- device not ready 

0D- illegal use of File Control Block 

12 - illegal operation (write a read file, etc.) 

15- bad file name 


CP/68 SYSTEM ERROR MESSAGES 


FORMAT ERROR The command line does not conform to the 
syntax specified for the command. 

NUMBER ERROR A bad numeric argument is present. 

The drive number is out of range or 
is not followed by a colon. 

FILE NOT FOUND The requested file could not be found. 

DISK ERROR:aa AT SECTOR bb, TRACK cc 

This error message comes from the 
INITIALIZE command. The error type (aa) 
is a device-error number. 


SYNTAX ERROR 
INVALID SET PARM 

These error messages come from the SET 
command. They indicate a bad SET 
command line. 
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The following errors come from PIP: 

BAD INPUT (OUTPUT) 

A device error; usually accompanied 
by a device-error message. 

ILLEGAL INPUT (OUTPUT) DEVICE 

Refers to attempts to use a device in 
an invalid manner, such as reading from 
a lineprinter. 

BUFFER OVER-RUN 

An overly long input line was encountered. 
The input file is probably the wrong type 
for the operation desired. 


ILLEGAL SWITCH 

Indicates a syntax error in the switch portion 
of the command line. 

READ (WRITE) ERROR 

Encountered in disk-to-disk copying; 
accompanied by a device error message. 

DIRECTORY ERROR 

The directory on a disk could not be read 
properly. This message is usually 
accompanied by a device-error message. 


CHECKSUM ERROR 

The checksum of a hex-formatted file 
was not correctly read. 

Additional errors are: 


SUBMIT FILE ERROR The filename in the SUBMIT command 

line could not be found or was not 
a TEXT file. 

ILLEGAL FILE TYPE The file specified for LOAD was 

not a binary file. 

RENAMING ERROR 
DUPLICATE NAME 
SECURITY ERROR 


These errors messages come from the RENAME command. RENAMING ERROR 
indicates some form of disk error in accessing the drive containing the 
old file. DUPLICATE NAME indicates that the new name already exists on 
the disk. SECURITY ERROR indicates that the old file is protected from 
renaming, (access code=01 or 02) 
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UNABLE TO CHAIN: filename.ext 


This error message indicates that a CHAIN request was made to the 
CP/68 system with filename.ext but it cannot be done, (no such file, disk 
read error, file not the right type, etc.) 

FILE DELETE-PROTECTED 

This file is protected from deletion (access code 02). It cannot 
be deleted until its access code is reduced. 

DELETE ERROR-OPEN OUTPUT FILES 

As long as any output files are open CP/68 cannot delete a file on 
that disk. 
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Part 2 


Advanced User's Guide 

»»****«s**»x********» 


INTRODUCTION 


CP/68 is fully relocatable, supports dynamic disk files on 
multiple drives, has a clean and logical command structure, 
provides device-independent I/O, and has features which 
facilitate complex system operations. It requires slightly less 
than 8K bytes of contiguous memory plus a section of base-page 
(0020H to 0046H). Transient files overlay some system commands 
and user files. User files can chain in new files. Files can be 
used as a source of system commands. 

CP/68 provides an extensive set of "extended instructions" 
which greatly add to the power of the 6800 instruction set. 
These "extended instructions" were used frequently in CP/68 
itself. This portion of the book describes the structures and 
algorithms used in CP/68 in sufficient detail to allow you to 
add functions to the system and to interface your own programs 
to CP/68. 
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CP/68 DATA STRUCTURES 


CP/68 uses several data structures in memory to perform various 
functions. These data structures are involved in all I/O operations, and 
some of the other system operations. The data structures discussed in 
this section include: Base-page, Equipment table, Physical device table, 
Request-control block (RCB), File-control block (FCB), File information 
block (FIB), and stack. 

BASE-PAGE 

CP/68 uses an area of base-page memory from address 0020H to 0047H 
to store global variables and system parameters. Most of these locations 
deal with I/O, while others are involved with command parsing and other 
functions. 


Command-parsing variables 


DESCRA 0020H 

This 2-byte location stores the address in memory of the beginning 

character of a token. (For a description of "tokens", see the CP/68 
operation NXTOK) 

DESCRC 0022H 

This byte stores the number of characters in the current token. 

CUCHAR 0023H 

This 2-byte location stores the address of the next character in the 

command line to be processed. Typically, this means that 

CUCHAR=DESCRA+DESCRC+1. CUCHAR is initialized to the beginning of the 
command line when it is desired to parse that line. DESCRA is 
automatically set by the NXTOK operation. To back up a token, set 
CUCHAR=DESCRA. 

RC 0025H 

This byte returns the return-code of the extracted token. (See NXTOK for 
a description of token codes.) 

CLASS 0026H 

This byte returns the class of the extracted token. The class is a sub¬ 
classification of the RC. (See NXTOK for a description of token classes.) 

VALUE 0027H 

This 2-byte location stores the binary value of a numeric token when one 
is encountered during parsing. It is an unsigned 16-bit number. 
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Conversion from hex or decimal bases is done automatically by CP/68. 


Disk information locations 


FCBCHN 0029H 

This 2-byte location stores the address of the header of the linked list 
of open file-control blocks. If FCBCHN is zero, there are no open files. 
If FCBCHN is not zero, it contains the address in memory of the first FCB 
that is active. Each FCB contains a pointer to the next FCB. If the 
pointer is zero, the end of the chain has been reached. 

FRETAB 002BH 

This is a table consisting of four, 2-byte entries. Each entry 
corresponds to one of the four disk drives maintained by CP/68. The entry 
stores the track and sector numbers of the header of the free-space chain 
on that disk. When a disk is being used, CP/68 copies the header data 
into the FRETAB entry so that it does not have to continually read the 
data from the disk. The entries are cleared when CP/68 is re-started. 

Unused locations 


0033H to 0039H Reserved for future expansion. 

Console parameters 


BS 0039H 

This byte is the character to be used as a backspace on the console 
device. The default value for BS is 08 hex. 

DL 003AH 

This byte is the character to be used as the line-delete on the console 
device. The default value for DL is 15 hex (control-U). 

DP 003BH 

This byte is the number of lines per page on the console device. The 
default value for DP is 00 hex. (no limit on page depth) 
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DPCNT 003CH 


This byte is used as the counter for the lines on a page on the console 

device. When DPCNT=DP, the end of a page has been reached. DPCNT is 

initialized to 01 hex. 

WD 003DH 

This byte is the number of characters per line on the console device. The 

default value for WD is 00 hex. (no limit on line width) 

NL 003EH 

This byte is the number of nulls which will be output with each linefeed 
on the console device. This feature allows linefeed delays for consoles 
which need such delays. The default value for NL is 00 hex. 

TB 003FH 

This byte is the character to be recognized as a tab on the console 
device. The default value for TB is 09 hex. (control-I) 

DX 0040H 

This byte is a switch which determines if the console device is to echo 
input characters. (Full or half duplex) If DX=00, the console is full- 
duplex and will echo all input. If DX=FF, the console is half-duplex and 
will not echo. The default value for DX is 00 hex. (full duplex) 

EJ 0041H 

This byte is the number of linefeeds to be output at the end of a page on 
the console device. The default value for EJ is 00 hex. 

PS 0042H 

This byte is a switch which controls the "pause" feature on console 
output. If PS=00, the console will wait at the end of a page of output 
until an escape character is input. (See ES below) If PS is not zero, the 
console will not pause. The default value of PS is FF hex. (no pause) 

ES 0043H 

This byte is the character to be interpreted as an "escape" on console 
input. The default value for ES is IB hex. (ASCII "ESC") 
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Lineprinter parameters 


LDP 0044H 

This byte sets the number of lines per page on the lineprinter device. 
The default value for LDP is 60 decimal. 

LDPCNT 0045H 

This byte stores the count of lines on a page of lineprinter output. When 
LDPCNT=LDP, a full page has been output. The value of LDPCNT is 
initialized to 00 hex. 

LWD 0046H 

This byte sets the number of characters on a line for the lineprinter 
device. The default value for LWD is 80 decimal. 

EQUIPMENT TABLE (EQTAB) 


The Equipment table, in conjunction with the Physical-device table, 
vectors I/O using the device name provided by the user in the RCB or FCB. 
Each table contains an entry for each physical device in CP/68. The 
physical devices are: Console (CON), Papertape reader (PTR), Papertape 
punch (PTP), Disk (DSK), Lineprinter (LPT), Magnetic tape (MTA), Teletype 
or alternate Console (TTY), and Null device (NUL). The CON device is the 
command source. It must be capable of input and output of ASCII 
characters. The CON "SET" parameters control its behavior. The PTR device 
is input only. The X-ON (11 hex) and X-OFF (13 hex) characters are used 
to turn PTR on and off. Linefeeds (0A hex) and nulls (00 hex) are 
swallowed. The PTP device is output only. A linefeed (0A hex) is issued 
with each carriage return (0D hex) and 4 nulls (00 hex) are added. The 
DSK device is a floppy-disk drive. The details of its operation are 
handled in the system code. The LPT device is an output-only printer. The 
LPT "SET" parameters control its behavior. The formfeed (0C hex) 
character is used to control paging on the LPT device. Linefeeds (0A hex) 
are automatically provided with each carriage return. (0D hex) The MTA 
device is unsupported in the present CP/68. The NUL device is actually 
not a device at all but simply a "bit bucket" or "do nothing". This 
proves useful at times to check out programs. Each device is given a 
three-character name. 


Each entry in the equipment table has three 2-byte fields. The first 
field is the address of an input routine for that device. This routine 
must handle a line or block of data; CP/68 does not use character or 
single-byte 1/0. If the device does not support input (the LPT for 
example), then the NUL handler is used. The second field is the address 
of an output routine for that device. This routine must also handle a 
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line or block of data. If the device does not support output (the PTR for 
example), the the NUL handler is used. The third field is the address of 
the interface used by that device. 

As supplied, CP/68 assumes the following: 

CON ACIA at 8008H 

PTR ACIA at 8010H 

PTP ACIA at 801 OH 

DSK special case...the handlers for this device have 

interface addressing built in. 

LPT PIA at 8002H 

MTA not implemented in the current version. 

TTY ACIA at 8010H 

NUL no device needed 

Note that the PTR,PTP, and TTY devices are set up to share one interface. 
This allows using the papertape facilities of a teletype (ASR-33) as well 
as its keyboard/printer. Note that CP/68 initializes the CONsole ACIA 
device, the TTY ACIA device, and the LPT PIA device on cold start. Other 
devices will need to be initialized by the user. An example Equipment 
table entry is shown below. 

CONSOL FDB INLIN input a line from the console 
FDB OTLIN output a line to the console 
FDB $8008 ACIA at address 8008H 


PHYSICAL DEVICE TABLE (PDTAB) 


This table vectors I/O calls to the proper entry of the equipment 
table. Each entry in this table consists of three fields. The first field 
is the three-character name of the device; the second field is the 
address of the entry in the equipment table which services the physical 
device; the third field is also the address of the equipment table entry. 
The use of both fields allows for reassignment of a physical device. 
Suppose, for example, that you wanted to use the TTY device as the 
console. (See the ASSIGN command) You would modify the second entry of 
the physical-device table CON entry to point to the TTY entry of the 
Equipment table. All I/O directed to CON would then be vectored to the 
TTY device using the TTY handlers. The third field of the physical-device 
table entry is used to maintain a pointer to the original address of the 
device. Thus, no matter how many times a device may have been re¬ 
assigned, there is still a pointer to its original Equipment-table entry. 
This is needed by some CP/68 commands, such as STATUS. Hence, each entry 
in the physical-device table has seven bytes. As an example, here is the 
CON entry. 

FCC 'CON' name is CON 

FDB CONSOL Equipment table pointer 

FDB CONSOL "same" 


22 


(c) Hemenway Associates, Inc., 1979 



The physical-device table uses a zero entry as an end marker. 


REQUEST-CONTROL BLOCK (RCB) 


All requests for I/O through CP/68 require a data structure in 
memory called an RCB or FCB. An RCB consists of 9 bytes of memory. Disk 
I/O requires the extended block (FCB). All other I/O requests may use an 
RCB. There are five fields in an RCB; three must be filled in by the user 
and the system provides the other two. The structure of an RCB is as 
follows: 

RCBEQT supplied by the system 

This 2-byte space is the address of the EQTAB entry which applies to this 
request for I/O. 

RCBGDT required from user 

This three-byte space must contain the three-character name of the device 
from-or-to which I/O is desired. CP/68 looks up this name in PDTAB and 
uses the entry there to find the EQTAB entry which it stores in RCBEQT. 

RCBSTA supplied by the system 

This byte is the status of the I/O request. It should be cleared before a 
CP/68 I/O request is issued. It returns any error conditions. It is zero 
for successful I/O completion. If RCBSTA returns nonzero, an error has 
occured. 

RCBDTT required from user 

This byte is a switch to choose input or output. If RCBDTT=0, then input 
is being requested. If RCBDTT=FF, then output is being requested. 

RCBDBA required from user 

This 2-byte space should contain the address in memory of a buffer to be 
used for I/O. It is up to the user to provide sufficient space in the 
buffer. 

Example of RCB setup for CONsole input 

RMB 2 space for RCBEQT 

FCC 'CON 1 RCBGDT 

FCB 0 RCBSTA 

FCB 0 RCBDTT input 

FDB BUFFER buffer address 

Example of RCB setup for PTP output 
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RMB 2 
FCC 'PTP * 
FCB 0 
FCB $FF 
FDB BUFFER 


space for RCBEQT 

RCBGDT 

RCBSTA 

RCBDTT output 
buffer address 


To access fields in the RCB, the following EQUates will be useful. 

RCBEQT EQU 0 
RCBGDT EQU 2 
RCBSTA EQU 5 
RCBDTT EQU 6 
RCBDBA EQU 7 

Now, if the index register points to the RCB address... 

LDA A RCBSTA,X get the status 

LDX RCBDBA,X get the buffer address 

and so on. 


FILE-CONTROL BLOCK (FCB) 


This data structure is an extended RCB with additional fields necessary 
for disk I/O. It consists of 42 bytes of memory. The first five fields 
are identical to the RCB fields. 

FCBEQT=RCBEQT 
FCBGDT=RCBGDT 
FCBSTA=RCBSTA 
FCBDTT=RCBDTT 
FCBDBA=RCBDBA 

There are 14 additional fields in an FCB. 

FCBDRV required from user 

This byte must contain the drive number of the disk containing the 
desired file. Drive numbers run from 0 upwards. 

FCBTRK supplied by system 

This byte must contain the track number of the desired sector on the disk 
in FCBDRV. 

FCBSCT supplied by system 

This byte must contain the sector number desired on FCBTRK. 
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FCBFWD supplied by system 

This 2-byte space is filled in by CP/68 with the forward link (track and 
sector) of the requested sector in disk reads and writes. 

FCBBAK supplied by system 

This 2-byte space is filled in by CP/68 with the backward link (track and 
sector) of the requested sector in disk reads and writes. 

FCBNAM required from user 

This 13-byte field must contain the file name and extension of the 
desired file for use by the file-manager of CP/68. The file name must be 
exactly 8 characters; pad with blanks as necessary to fill 8 characters. 
The ninth character must be a period. "." The extension must be exactly 
three characters; pad with blanks as necessary to fill 3 characters. The 
13th character should be an "end-string" character. (04 hex) A system 
function is provided to format a string of characters into this internal 
form...see FMTS. 

FCBTYP user supplied for new file, system supplied for 
existing file 

This byte gives the type of file. If a new file is being created, the 
user should set this byte as follows: 

00 binary file 

01 binary file with transfer address (runable) 

02 random file 
03 text or hex file 

Other numbers may be used, but CP/68 type-checks files that are loaded 
into memory, copied, etc. If the file already exists, the file manager 
will fill this field with the file type. 

FCBACS user supplied for new file, system supplied for 
existing file 

This byte gives the access code of the file. If a new file is being 
created, the user should set the byte as follows: 

00 no protection 

01 file can be renamed but not deleted 

02 file can neither be renamed or deleted 

If the file already exists, the file manager will fill this byte with the 
access code of the file. 

FCBFTS supplied by system 

This 2-byte field is filled by the system with the first track and sector 
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of the named file 


FCBLTS supplied by system 

This 2-byte field is filled by the system with the last track and sector 
of the named file 

FCBNMS supplied by system 

This 2-byte field is filled by the system with the number of sectors used 
by the named file. 

FCBNFB supplied by system 

This 2-byte field is filled by the system with a link to the next active 
FCB in the system. If this is the most recent FCB in the system, the link 
will be zero. (See FCBCHN in base-page) 

FCBIND supplied by system 

This 2-byte field is filled by the system with a pointer to the buffer 
supplied at FCBDBA. This pointer indicates the present data byte in the 
buffer. 


FCBSCF required from user 

This byte is a switch to control space-compression in text files. If 
FCBSCF=0 then no space-compression is performed. If FCBSCF is nonzero, 
then all spaces within a file (20 hex) will be compressed as follows: 

Any data byte =20 hex will be compressed. Spaces are replaced by the 
negative (2's-complement) of the number of sequential spaces. Hence, if 
the file contained the following 5 bytes of data: 

41 20 20 20 41 'A A* 

it would be compressed to read 

41 FD 41 


where FD=-3 . 


When a file is read back with FCBSCF nonzero, spaces are re-inserted 
where necessary. Only files of ASCII text should be compressed. 


Example of FCB setup to read file MYFILE.TXT on disk 1 


RMB 2 
FCC 'DSK* 
FCB 0 
FCB 0 

FDB BUFFER 


FCBEQT 

FCBGDT=DSK 

FCBSTA 

FCBDTT=input 
sector buffer address 
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FCB 1 FCBDRV=1 

RMB 1 FCBTRK 

RMB 1 FCBSCT 

RMB 2 FCBFWD 

RMB 2 FCBBAK 

FCC 'MYFILE » 

FCC 

FCC 'TXT* FCBNAM 

FCB $04 

RMB 1 FCBTYP 

RMB 1 FCBACS 

RMB 2 FCBFTS 

RMB 2 FCBLTS 

RMB 2 FCBNMS 

RMB 2 FCBNFB 

RMB 2 FCBIND 

FCB $FF FCBSCF (compression on) 

Here is a set of EQUates which will ease access of FCB fields. 

FCBEQT EQU 0 
FCBGDT EQU 2 
FCBSTA EQU 5 
FCBDTT EQU 6 
FCBDBA EQU 7 
FCBDRV EQU 9 
FCBTRK EQU 10 
FCBSCT EQU 11 
FCBFWD EQU 12 
FCBBAK EQU 14 
FCBNAM EQU 16 
FCBTYP EQU 29 
FCBACS EQU 30 
FCBFTS EQU 31 
FCBLTS EQU 33 
FCBNMS EQU 35 
FCBNFB EQU 37 
FCBIND EQU 39 
FCBSCF EQU 41 

Thus, if the index register points to the FCB address 

LDA A FCBFWD,X get forward link track 

LDA B FCBFWD+1,X get forward link sector 

STA A FCBTRK,X put into track 

STA B FCBSCT,X put into sector 


and so on. 
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FILE-INFORMATION BLOCK (FIB) 


This data block contains the information in the file directory on disk. 
Each file has a FIB, consisting of 32 bytes. In the present CP/68, only 
the first 20 bytes are used. The FIB fields match the FCB fields starting 
with FCBNAM and ending with FCBNMS. 

FIBNAM=FCBNAM 
FIBTYP=FCBTYP 
FIBACS=FCBACS 
FIBFTS=FCBFTS 
FIBLTS=FCBLTS 
FIBNMS=FCBNMS 

The FIBNAM field is always maintained in the proper format. The following 
EQUates will ease the access of FIB fields. 

FIBNAM EQU 0 
FIBTYP EQU 13 
FIBACS EQU 14 
FIBFTS EQU 15 
FIBLTS EQU 17 
FIBNMS EQU 19 


STACK 

CP/68 contains its own stack in its RAM space. Cold or warm starts 
reset the stack pointer to the system stack location. 

CP/68 provides a 256 byte stack which is quite ample. Since system 
calls are done via software interrupts, and the stack is used for 
parameter passage, a minimum of 100 bytes of stack is needed to run CP/68 
successfully. 


DO NOT UPSET THE CP/68 STACK POINTER! 
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CP/68 DISK FORMAT 


A disk initialized for CP/68 (see INITIALIZE command) has some data 
structure written onto it which CP/68 uses to work with files. These data 
structures must be maintained or CP/68 may do unpredictable things to the 
disk. An uninitialized disk will not work with CP/68. 

Track 0 

The first track on the disk (track 0) is reserved for the system. The 
first sector (sector 1) is used for bootstrap space, system linkage, and 
the free-space header. If SECSIZ is the number of bytes per sector on the 
disk, then 

SECSIZ-5 first track of system-linked file 

SECSIZ-4 first sector of system-linked file 

SECSIZ-3 last track of system-linked file 

SECSIZ-2 last sector of system-linked file 

(These values are written by the LINK command) 

SECSIZ-1 track of first free sector 

SECSIZ sector of first free sector 

(These values are initialized by INIT, updated by file manager.) 

The beginning SECSIZ-6 bytes of the first sector of the first track 
provides space for a bootstrap program. The remainder of track 0 is space 
for the file directory information. Files are described by 32-byte FIB 
blocks that are stored sequentially as long as there is space. The 
directory space is initialized to all zero by INIT. 

A directory search is terminated when a zero is found at the start 
of a FIB block. A FIB is removed from the directory by placing a blank in 
the first character of the file name field (first byte of FIB). This does 
not recover the file’s sectors, however. The DELETE function is provided 
to both remove a FIB and replace the file’s sectors on the free-space 
list of the disk. The next file to be created will use that space. 

Tracks 1-n 

The rest of the tracks on the disk are used as CP/68 file space. Every 
sector has forward and backward links in its first four bytes. These 
links are automatically maintained by the system. Hence, each sector has 
SECSIZ-4 usable bytes. An initialized disk has its sectors linked in a 
pattern found to optimize access times, not usually in a sequential 
manner. The free-space chain header on track 0 points to the start of 
this list; sectors are allocated to files from this list and links 
changed accordingly. Deleted files return their sectors to the head of 
the free-space list. A much-used disk will become ’’fragmented”—the links 
will be very far from sequential. This increases access times, but CP/68 
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will not lose data as long as the links are maintained. The PIP command 
provides a way to "compact" a disk that has become fragmented. 

(Note: the backward links are not used in the present CP/68.) 


ISSUING SUPERVISOR CALLS (SVC) 


CP/68 was written to be relocatable. Each routine could not have an 
absolute address. Also, it was desired that routines have standardized 
calling sequences and that registers be saved in most cases. The 
mechanism of the 6800 software interrupt was used to solve the problem of 
calling CP/68 routines. CP/68 has only two entry points: the cold start 
at its first byte, and the software-interrupt handler (SWIHDR) three 
bytes later. All system calls are performed by a software interrupt (SWI) 
instruction followed by a routine number. These two bytes are 
collectively referred to as an SVC. CP/68 automatically vectors the call 
to the appropriate address. The SWI saves the registers on the stack and 
recovers them on return from the system. Those routines that use 
registers for parameters manipulate them on the stack. Once CP/68 has 
been called, the stack contains: 

stack pointer: 

SWIHDR return address 
condition code byte 
accumulator B 
accumulator A 
Register X 
Return address 

Thus, the following code would recover the contents of 
the B accumulator. 

TSX 

LDA B 3,X 

The following would return the condition codes to the user. 

TPA 

TSX 

STA A 2,X 


Since each CP/68 routine call is done in the same way, SWI and a byte, 
they can be made macros and used like new instructions. For example, 
CP/68 has a routine to read a byte from an open file. It would be called 
as follows: 


SWI call CP/68 

FCB 24 file-read 
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A macro could be written: 


READ MACRO 
SWI 

FCB 24 
MEND 

so that whenever a file read was desired, a READ instruction could be 
given. CP/68 was written with the express purpose of providing a list of 
useful "extended instructions". 

Using the software-interrupt mechanism, up to 256 different system 
calls are possible. In fact, CP/68 uses only 54 of these, (numbered 0-53) 
An SWI followed by any number larger than 53 will be vectored to the 
usual SWI trap in the underlying monitor. (Check the SWIHDR routine for 
the location of this trap.) Thus, breakpointing can be done in CP/68 with 
a two-byte "SWI" 

SWI call CP/68 

FCB $FF force call to monitor 

which will operate exactly like the simple SWI did without it. Programs 
that use SWI instructions must be modified to add the second byte, or 
CP/68 routines will be called with unpredictable results. 
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SVC ROUTINES 


General instructions 
00 PSHAL 

This routine pushes all the register contents onto the stack in the 
normal 6800 order. 

01 PULAL 

This routine is the reverse of PSHAL. It restores the register contents 
from the stack. 

02 TXAB 

This routine transfers the contents of the index register to the A and B 
accumulators. The high byte goes into A, the low byte into B. The index 
register is undisturbed. 

03 TABX 

This routine is the reverse of TXAB. The contents of the A and B 
accumulators are transfered into the index register. The contents of A 
and B are not disturbed. 

04 XABX 

This routine exchanges the contents of the index register and the A and B 
accumulators. A and B become X, X becomes A and B. 

05 PSHX 

This routine pushes the contents of the index register onto the stack. 
The low byte is pushed first, followed by the high byte. No registers are 
disturbed. 

06 PULX 

This routine is the reverse of PSHX. The index register is loaded from 

the stack. Only the index register is changed. 

07 ADXAB 

This routine adds the 16-bit unsigned contents of the index register to 
the combined 16-bit value in the A and B accumulators. The result is left 
in A and B, X is unchanged. The condition codes are set to reflect the 
results of the addition. 
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08 


ADABX 


This routine works like ADXAB except that the result is left in X, A and 
B are unchanged. The condition codes reflect the results of the addition. 

09 ADDAX 

This routine adds the unsigned byte in the A accumulator to the 16-bit 
unsigned value in the X register. The result is in the X register, A is 
unchanged. The condition codes reflect the result of the addition. 

10 ADDBX 

This routine is like ADDAX except that the B accumulator is used. The 
condition codes reflect the results of the addition. 

11 SBXAB 

This routine subtracts the 16-bit unsigned value in the index register 
from the combined 16-bit value in the A and B accumulators. The result is 
left in A and B, X is unchanged. The condition codes are set to reflect 
the results of the subtraction. 

12 SBABX 

This routine is like SBXAB except that the result is left in X, A and B 
are unchanged. The condition codes reflect the results of the 
subtraction. 

13 SUBAX 

This routine subtracts the unsigned byte in the A accumulator from the 

16-bit unsigned value in the index register. The result is left in the 
index register, A is unchanged. The condition codes are set to reflect 
the result of the subtraction. 

14 SUBBX 

This routine is like SUBAX except that the B accumulator is used. The 
condition codes reflect the results of the subtraction. 

15 MUL8 

This routine multiplies the unsigned bytes in A and B accumulators and 
puts the resulting 16-bit value high byte in A, low byte in B. The 
condition codes are set to reflect the product of the multiplication. 
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16 


MUL16 


This routine multiplies the unsigned 16-bit value in the index register 
by the 16-bit value in the A and B accumulators. The 32-bit result is 
left in A,B,X . The condition codes are set to reflect the result of the 
multiplication. 

17 MOVC 

This routine moves up to 256 bytes from one place to another. The from- 
address and to-address are placed on the stack, (to-address first, 
followed by from-address.) The byte count is passed in the B accumulator. 
On return, B=0, the stacked addresses have been incremented B times, and 
A is undisturbed. 

Example: LDX TOADDR 

PSHX 

LDX FRMADDR 
PSHX 

LDA B #100 
MOVC 
INS 
INS 
INS 
INS 

18 CMPC 

This routine compares two strings. It can be used for comparing text 
strings or other data. It can compare strings of up to 256 bytes in 
length. If the "end-string" character (04 hex) is found in either string, 
comparison is terminated. The parameter setup is the same as MOVC—the 
addresses of the two strings are stacked and the byte count goes into 
accumulator B. The result of the comparison is returned in the condition 
codes. 

Example of using CMPC 


get to-address 
use CP/68 
get from-address 
use CP/68 
move 100 bytes 
move them 

clean stack 


LDX #STRNG2 
PSHX 

point to second string 

LDX #STRNG1 
PSHX 

point to first string 

LDA B #10 

compare 10 characters 

CMPC 

INS 

compare 

INS 

INS 

clean stack 

INS 


BGT- 

was string 1 > string 2? 
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so that if STRNG1 = ’AAAAAAAAAAAAAAAAAAAAAAAA* and if 
STRNG2=’BAAAA ', then the branch would 
not be taken. 

45 MOVS 

This routine works like MOVC except that it does not use a byte count in 
the B accumulator. The move continues until an "end-string" (04 hex) is 
found in the from-string. 

46 INDEX 

This routine adds the product of the unsigned bytes in the A and B 
accumulators to the 16-bit unsigned value in the index register. The 
result is left in the index register, A and B are unchanged. The 
condition codes are set to reflect the results of the operation. 

50 DIV16 

This routine divides the unsigned 16-bit value in the combination of the 
A and B accumulators by the 16-bit unsigned value in the index register. 
The quotient is returned in the A and B accumulators. The remainder is 
returned in the index register. The condition codes are set to reflect 
the quotient value. 


Command-parsing routines 


47 NXTOK 

This routine breaks up a command line into "tokens". A token is a 
substring of the command line which is treated as a unit. CP/68 defines 
the following tokens: 

NAME A name is a string of characters which begins with an 
alphabetic character and contains only alphanumeric 
characters, (no imbedded spaces) 

NAME WITH WILD-CARD CHARACTERS 

A name which may include the special characters "*" and 

NUMBER A string of digits which may be decimal or hexadecimal. 

Hexadecimal numbers must begin with a dollar sign. ($) 

DELIMITER 

One of the special characters defined by CP/68. 

This includes the period (.), comma (,), colon 
(:), dollar sign ($), equals sign (=), semicolon 
(;), and the arithmetic routines +,-,and / 
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CARRIAGE RETURN 


The ASCII carriage return character. (OD hex) 

ERROR A token not falling into one of the above classes. 

NXTOK uses base-page for its parameters. Scanning the command line begins 
at the character whose address is in CUCHAR. The address of the first 
character of the token is returned in DESCRA. Note that spaces are not 
part of any token. Spaces are skipped over by NXTOK unless they are 
imbedded in a token. The count of the number of characters in a token is 
returned in DESCRC. The base-page locations RC and CLASS return the 
classification of the token as follows: 

NAME RC=01 CLASS=02 

NAME (WCRD) RC=02 CLASS=02 

NUMBER RC=03 CLASS=02 

DELIMITER RC=ASCII code of character CLASS=04 

CARRIAGE RET. RC=0D hex CLASS=0D hex 

ERROR RC=00 CLASS=00 

CUCHAR is returned pointing one character beyond the end of the present 
token. If the token is a number (RC=03)> then its binary value is 
returned in the base-page location VALUE. NXTOK will automatically 
convert unsigned decimal or hexadecimal numbers into binary form. The hex 
numbers must have a leading dollar sign. ($) NXTOK will trap numbers that 
are too large (>65535 or FFFF hex) as errors. 

Example of use of NXTOK 

command lines'LOAD 1rMYFILE.EXT ' carriage return 

first tokens'LOAD' RC=01, CLASS=02 

second tokens' 1* RC = 03, CLASSs02, VALUEsOOOl 

third tokens':' RCs3A, CLASSs04 

fourth tokens'MYFILE' RC = 01, CLASS = 02 

fifth tokens'.' RC=2E f CLASSs04 

sixth tokens'EXT' RCsOI, CLASSs02 

seventh tokensc.r. RCsOD, CLASSsQD 
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Basic Input/output handling 


19 IOHDR 

This is the basic I/O routine in CP/68. It is called with the address of 
the RCB or FCB in the index register and it causes the system to perform 
the I/O operation. No registers are disturbed by this routine. IOHDR 
handles entire lines or blocks of data at once. All CP/68 devices are 
handled through IOHDR, although some additional routines are provided for 
disk I/O and special cases of system I/O. The status of the I/O request 
is returned in RCBSTA (or FCBSTA). 

Example of use of IOHDR to write character string on terminal 

LDX #RCB point to RCB 

IOHDR 

where the RCB has been set up as follows: 

RCB RMB 2 space for EQTAB 

FCC 'CON' console device 

FCB 0 status 

FCB $FF output 

FDB DATA address of data characters 

DATA FCC 'THIS STUFF WILL BE PRINTED' 

FCB $0D carriage return 

Note that a carriage return was used to indicate the end of a line. CP/68 
will add a linefeed automatically for CON, TTY, or LPT I/O. If a new 
line is not desired, use an "end-string" (04 hex) in place of the 
carriage return. 

Reading or writing a disk sector is done through IOHDR by some additional 
setup in the FCB. The FCBGDT must be 'DSK'. The FCBSTA is cleared. The 
FCBDTT is set to 00 for reading or FF for writing. The FCBDBA is set to 
point to a sector buffer. The FCBDRV is set to the desired drive number. 
The FCBTRK is set to the desired track number. The FCBSCT is set to the 
desired sector number. IOHDR will perform the read or write to/from the 
indicated sector on the indicated disk. Any disk sector can be accessed 
in this manner. The only error checking performed is that the desired 
sector exists on the disk and that the desired operation can be performed 
by the drive. The user is warned that IOHDR does not preserve the links 
or other data structures on the disk. This is done by the routines READ, 
WRITE, etc. 
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30 


PRTERR 


This routine prints error messages for device I/O errors. It is called 
with the address of an RCB or FCB in the index register. If the status 
(RCB or FCBSTA) is zero (good), it does nothing. If the status is 
nonzero, it prints an error message on the console device. The error 
message is of the form: 


AAA ERROR: BB 

where AAA is the device name (RCB or FCBGDT) and BB is the status value 
(RCB or FCBSTA) in hexadecimal. 

48 GTCMD 

This routine accepts a command line from the console. The user is 
prompted and a new line may be typed in. GTCMD passes the line directly 
to NXTOK, so on return from GTCMD, the first token on the line has been 
parsed. If the user desires to back up to the start of the line, set 
CUCHAR=DESCRA in base page. 

49 PRTMSG 

This routine prints a string on the console device. The index register is 
pointed to the start of the string. If the string terminates with a 
carriage return, a new linefeed is issued. If the string terminates with 
04 hex, no linefeed is issued. 


Filename formatting 

44 FMTFCB 

This routine parses a complete file designation including drive number, 
filename, and extension, and places it properly formatted into an FCB. 
The format that FMTFCB expects is: 

[drive:] filename.ext 

where the drive number and colon are optional. If the drive number is 
omitted, drive 0 will be assumed. FMTFCB will allow no wild-card names; 
it works only with unambiguous file references. To use FMTFCB, place the 
address of the character string containing the file specification into 
CUCHAR in the base-page. Place the address of the FCB into the index 
register. FMTFCB will place the drive number into FCBDRV and the filename 
appropriately formatted into FCBNAM. Any error conditions are returned in 
FCBSTA. If FCBSTA=00, the file specification was correctly formatted. If 
there was some error, FMTFCB returns an error status=21 . 
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52 


FMTS 


This routine formats a filename from the input form which may vary in 
length to the fixed internal form. It also handles the expansion of wild¬ 
card characters. The calling sequence is like MOVC, with from and to 
addresses on the stack and a byte count in the B accumulator. The from- 
address is typically the start of a token in the command line. The to- 
address is typically the FCBNAM field of an FCB. The byte count is the 
total length of the name; the sum of the length of the three tokens 
(name, . , ext) which comprise it. FMTS expands the wild-card character 
into a string of "? n of the proper length. FMTS returns a condition 
byte in the B accumulator as follows: 

B=00 unambiguous name 

B=01 ambiguous name (wild-cards found) 

B=02 bad name (error) 

Example of the use of FMTS 


CMDLIN FCC 'ABC?.*' 


length=6 characters 


LDX #FCB+FCBNAM 
PSHX 


LDX //CMDLIN 
PSHX 

LDA B #6 

FMTS 

INS 

INS 

INS 

INS 


point to FCB name field 
point to command line 

format name 
clean stack 


at this point, B=01 and the name field of the FCB contains 
ABC?"''*^.??? where indicates a space 

53 CMWC 

This routine compares strings like CMPC, except that it skips over the 
wild-card character "?" which matches any character, including a space. 
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Directory handling routines 


23 OPEND 

This routine accesses the directory track on a particular disk and 
returns a pointer to the first FIB on the disk. It is called with the 
index register pointing to an FCB which has the drive number set up in 
FCBDRV and 'DSK' in FCBGDT. The FCBDBA must point to a buffer large 
enough for one disk sector. The status (FCBSTA) is returned as follows: 

00=good 

01=end of directory found 
>1=error condition value 


If the status is good, the buffer (FCBDBA) contains the first sector of 
the directory from the indicated disk and FCBIND is initialized to the 
start of the first FIB. It is up to the user to check that the FIB is not 
a deleted file. This is done by looking for a space (20 hex) in the first 
byte of FIBNAM. Hence, if the index register points to an FCB which has 
FCBGDT, FCBDRV, and FCBDBA properly set, the following code will check 
for a valid FIB entry. 


OPEND 

TST FCBSTA,X 
BNE ERROR 

LDX FCBIND,X 
LDA A 0,X 
CMP A #$20 
BEQ N0G00D 


open directory 
good status? 
no, error! 

point to FIB 
check first byte 
space? 

if so, not valid 


Note that FCBSTA=01 indicates a totally empty disk. 


26 GETDR 


This routine gets subsequent directory entries from a disk after OPEND 
has been used. Each call to GETDR will move the pointer FCBIND to the 
next FIB in the sector buffer. GETDR automatically reads new directory 
sectors as necessary until the end of the track is encountered. The 
calling sequence for GETDR is the same as that for OPEND: address of FCB 
in the index register and status returned in FCBSTA. 

27 PUTDR 

This routine is used to put a new FIB into a disk directory. It assumes 
that OPEND and GETDR have been used to find a spot for the new FIB where 
it will overlay either a deleted FIB or the next unused FIB on the disk. 
It assumes that the necessary file specification has been placed into the 
FCB (FCBNAM, FCBTYP, FCBACS, FCBFTS, FCBLTS, and FCBNMS) The index 
register is pointed to the FCB. PUTDR will copy the FIB entries from the 
FCB to the disk directory location pointed to by FCBIND. Status 
information is returned in FCBSTA. 
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Disk-file sequential I/O 


20 OPEN 

This routine opens a disk file for an I/O operation. It is called with 
the index register pointing to an FOB which has been initialized with the 
appropriate information. To open an existing file, set the following: 

FCBGDTz'DSK’ 

FCBSTA=0 

FCBDTT=0 input 
FCBDBA=address of sector buffer 
FCBDRV=desired drive 
FCBNAM=filename, properly formatted 

FCBSCF=00 or FF depending on type of file (space compression) 

To create a new file, set all of the above plus the following: 

FCBDTT=FF output 
FCBTYP=desired file type 
FCBACS=desired file access code 

OPEN will check that a new file does not conflict with a file that 
already exists on the disk and check that a file opened for input 
actually exists. Error status is returned in FCBSTA. OPEN places the FOB 
on the active FOB chain (see FCBCHN on base-page). As many open files as 
desired may be kept in the system, as long as there is a unique FOB for 
each one. 

21 CLOSE 

This routine finishes the processing of an active file and removes its 
FOB from the active file chain. It is called with the address of the FCB 
in the index register. Error status is returned in FCBSTA. For new files, 
CLOSE pads the last incomplete sector with nulls (00) so that the file 
contains all the desired data. CLOSE updates the directory FIB of the 
file to include the last track/sector used (FIBLTS) and the number of 
sectors (FIBNMS). Once a file is closed, its FCB space and buffer may be 
reused. 

22 REWD 

This routine is actually a CLOSE followed by an OPEN on the same file and 
using the same FCB. It can only be performed on input files. The effect 
is to return the file pointers to the start of the file. REWD is called 
with the index register pointing to the FCB. Error status is returned in 
FCBSTA. 
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24 


READ 


This routine gets a data byte from an file opened for input. Bytes are 
read sequentially from the file. READ is called with the FCB address in 
the index register. It returns the data byte in the A accumulator. Error 
conditions are returned in FCBSTA. If the end of the file is reached, the 
status will return 08. READ cannot go beyond the end of the file. If 
space compression is set (FCBSCF=FF), READ will expand the compressed 
spaces into real spaces. (20 hex) 

25 WRITE 

This routine places data bytes into a file opened for output. Bytes are 
written sequentially into the file. WRITE is called with the data byte in 
the A accumulator and the index register pointing to the FCB. Error 
conditions are returned in FCBSTA. If space compression is set (FCBSCF=FF 
(hex)), WRITE will convert spaces (20 hex) into compressed internal 
format. 


Initialization and Warmstart 


31 WARMST 

This routine returns control to CP/68 from a running program. This is the 
proper way to terminate a program written to run under the CP/68 system. 
WARMST will reset the stack pointer to the system stack, close all open 
files on the FCB chain, clear the free-space entries in base-page, and 
prompt for a new command. 

51 INTDK 

This routine does all necessary initialization processes for the disk 
drives. CP/68 does this on cold-start. The user may use this routine if 
the drive initialization must be redone from outside CP/68. 


Deleting a file 


28 DELETE 

This routine removes an existing file from a disk. It is called with the 
index register pointing to an FCB which has FCBGDT='DSK', FCBDRV=desired 
drive, FCBNAM= filename properly formatted. DELETE checks the access code 
of the file to be sure that the file may be deleted. If FIBACS>00 , 
DELETE will issue an error message, set FCBSTA=18, and return. DELETE 
requires that all open output files on the disk be closed. If there are 
open output files on the disk, DELETE will issue an error message, set 
FCBSTA=18 and return. DELETE removes the FIB from the directory by 
putting a space in the first character of FIBNAM. It links the sectors of 
the file to the head of the free-space list on that disk. It updates the 
free-space header link as well. Error conditions are returned in FCBSTA. 
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Program chaining 


29 CHAIN 

This routine loads a new program file into memory and starts executing 
it. It uses LOADB to bring in the new file. CHAIN is called with the 
index register pointing to an FCB with the desired FCBDRV, FCBNAM, etc. 
CHAIN moves the data from the user FCB into a system space so that the 
new file may overlay the user FCB memory. If there was some error, CHAIN 
will issue an error message and return to the system for a new command. 
If the file to be CHAINed had no transfer address, this will be flagged 
as an error. If there was no error, the new file will begin execution at 
its transfer address. 

37 LOADB 

This routine loads a binary-format file into memory. The file type 
(FIBTYP) must be 00 or 01. If it is not, LOADB will issue an error 
message and return without changing memory. LOADB expects the index 
register to point to an FCB with FCBGDT='DSK’, FCBDRV, and FCBNAM set to 
the desired file specification. If an error condition is encountered 
while reading in the new file, LOADB will close the file and return to 
the system. If the file had a transfer address, it will be stored in the 
location VALUE in base-page. If there was no transfer address, VALUE will 
be zero. 


User entries 


32-36, 38-43 USR1-USR11 

These entries in the dispatch table of CP/68 (DSPTAB) are unassigned and 
are left for the user to add new routines. 


FORMAT OF CP/68 BINARY FILES 


Binary files under CP/68 (this class includes all transient commands, 
system utilities, SAVE files, etc.) are stored on disk in a binary format 
to conserve space. There are two types of data in a binary file: transfer 
address, and memory data. Each type of data is stored in a block of up to 
256 bytes. The format of a transfer address is: 


BYTE 1 transfer address mark (16 hex) 

BYTE 2-3 transfer address 


(c) Hemenway Associates, Inc., 1979 


43 



BYTE 1 
BYTE 2-3 
BYTE 4 
BYTE 5- 


memory data mark (02 hex) 

memory address 

count of data bytes 

data bytes exactly as in memory 


Memory data is loaded at the address specified with it. There may be 
more than one transfer address in a file. If so, the last one in the file 
will be used. The last sector of a binary file will be padded with nulls 
(00 hex) as necessary to complete the sector. This has no effect on 
memory loading. 


Binary files cannot be transfered to an ASCII device like the PTP or 
LPT. Similarly, files read from ASCII devices like the PTR or CON are not 
in the binary format. The system command PIP provides format conversions 
for these two formats. 
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he following examples illustrate usage of CP/68 routines to perform 
seful operations. They are not intended to be optimal programs, but 
imply to show how easy the CP/68 "extended instructions" make the task 
f dealing with files, etc. 

This example shows how to open, read, write, and close files for 
nput and output. It is assumed that the user will type filenames in at 
he console when prompted to do so. Six routines are presented here: 

OPENI open an existing file for input 
OPENO open a new file for output 
GETB get a byte from existing file 
OUTB put a byte out to new file 
CLOSI close the file being read 
CLOSO close the new file 


It is assumed that the disk system has been initialized by use of 
NTDK. Two FCBs are assumed, one for each file in use. In this example, 
t is assumed that SECSIZ=256 bytes. 


INFCB 

RMB 

2 


FCC 

»DSK» 


FCB 

0 


FCB 

0 


FDB 

INBUF 


RMB 

33 

OUTFCB 

RMB 

2 


FCC 

'DSK' 


FCB 

0 


FCB 

$FF 


FDB 

OUTBUF 


RMB 

33 


define input FCB 
direction (input) 

define output FCB 
direction (output) 


INBUF RMB 256 sector buffer for input 

OUTBUF RMB 256 sector buffer for output 


be examples assume that the EQUates for FCBs and base-page 
Dcations have been set up. 


OPENI LDX #INMSG 
PRTMSG 
GTCMD 

LDX DESCRA 
STX CUCHAR 
LDX #INFCB 

* 


prompt for input filename 
get filename from CONSOLE 

back up to first token 
point to FCB 


0PEN2 


CLR FCBSTA,X init. status 

CLR FCBSCF,X no space compression 
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TST FCBSTA,X 

error? 

* 

BNE FILERR 

yes, print error message 


OPEN 

open file 


TST FCBSTA,X 

error? 

ft 

BNE FILERR 

yes 

ft 

RTS 

done! 

OPENO 

LDX #OUTMSG 
PRTMSG 

prompt for file name 


GTCMD 

LDX DESCRA 

get user file name 


STX CUCHAR 

back up to first token 


LDX #OUTFCB 

point to FCB 

ft 

BRA OPEN2 

finish like OPENI 

FILERR 

PRTERR 

print error message 

« 

WARMST 

return to system 

ft 

INMSG 

FCC 'INPUT FILE?' 

« 

FOB $04 


OUTMSG 

FCC 'OUTPUT FILE?' 

FOB $04 

CLOSI 

LDX #INFCB 

point to FCB 


CLOSE 

close file 


TST FCBSTA,X 

error? 

ft 

ft 

BNE FILERR 

RTS 

yes 

CLOSO 

LDX #0UTFCB 

point to FCB 


CLOSE 

close file 


TST FCBSTA,X 

error? 

ft 

BNE FILERR 

RTS 

yes 

GETB 

PSH B 

save B accumulator 


PSHX 

save index register 


LDX #INFCB 

point to FCB 

ft 

READ 

read a byte from file 

* the A accumulator 

» 

now contains the byte read 


LDA B FCBSTA, 

X check status 
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« 

* 


CMP B #8 status=08 is end-file 

BEQ GETB2 

BRA FILERR otherwise, error 


GETB1 PULX recover index register 

PUL B recover B accumulator 

RTS 

« 


GETB2 set whatever EOF flag is desired 
BRA GETB1 


* byte to be written in A accumulator 

* 

OUTB PSH B 
PSHX 

LDX #OUTFCB 
WRITE 

TST FCBSTA,X 
BNE FILERR 

PULX recover index register 

PUL B recover B accumulator 

RTS 


save B accumulator 
save index register 
point to FCB 
write byte to file 
error? 
yes 


nd for good measure, here is how to rewind the input file. 

REWIND LDX #INFCB point to FCB 

REWD rewind file 

TST FCBSTA,X error? 

BNE FILERR yes 

RTS 

ere is another example of the power of CP/68 to do fairly complex tasks 
n a few simple lines. Suppose the user wishes to have one program load 
n another whose name is defined in the program. Assume that INFCB and 
NBUF exist from the previous example. 


LOADER LDX #FNAME 
STX CUCHAR 
LDX #INFCB 
FMTFCB 
PRTERR 

TST FCBSTA,X 
BNE QUIT 


point to desired file spec, 
store in base page pointer 
point to FCB 

format file spec, into FCB 
take care of errors 
error found? 
if so, quit 


LOADB 


load in new file 
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* 

* new file must not overlay INFCB or INBUF!!!! 

* 

PRTERR take care of errors 

TST FCBSTA,X error found? 

BNE QUIT if so, quit 

« 

LDX VALUE look at transfer address 
BEQ QUIT if zero, no transfer address 

« 

JMP 0,X go to transfer address 

* 

QUIT RTS 

* 

FNAME FCC 'OrMYFILE.BIN' 

FCB $0D carriage return 

A somewhat more complex example is this piece of CP/68 which searches a 
disk directory for an empty FIB location. It assumes an FCB and sector 
buffer set up like INFCB, etc. The track and sector of the slot (if 
found) are returned in FCBTRK and FCBSCT. Error status is returned in 
FCBSTA as follows: 

00=found slot 
01=no space available 
>1=error 

The value TRKSIZ is assumed to be EQUated to the number of sectors in a 
track of the disk. It is assumed that the A accumulator contains the 
desired drive to be searched. 

SEMPTY LDX #INFCB point to FCB 

STA A FCBDRV,X save drive number 
TXAB 

LDX #INBUF get buffer address 

XABX now X=FCB, A,B=INBUF 

STA A FCBDBA,X set buffer address into FCB 

STA B FCBDBA+1,X 

CLR FCBSTA,X init. status 

OPEND open directory of drive 

* 

SEMPT2 LDA A FCBSTA,X check status 

BEQ SEMPT3 status O.K. 

CMP A #1 end of directory? 

BEQ SEMPT4 yes 

« 

JMP FILERR otherwise error 

* 

SEMPT3 LDX FCBIND,X point to FIB 

LDA A 0,X check first byte 
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« 




* 

SEMPT4 


* 

« 


CMP A #$20 
BNE *+3 

RTS 

LDX #INFCB 
GETDR 

BRA SEMPT2 

LDA A FCBSCT,X 
CMP A #TRKSIZ 
BNE *+3 

RTS 

CLR FCBSTA,X 
RTS 


space? 

no 

yes, found an empty FIB 
point to FCB 

get next FIB from directory 
keep looking 

get sector number 
at end of track 0? 
no, found empty FIB 

yes, no room 

return good status 


The next example shows a second way to chain a new program in from 
another using CP/68. Using the CHAIN SVC, the new program can overlay the 
one that called it in. The assumptions of an input FCB, etc. are used 
here. 


LDX #MSG 

PRTMSG 

GTCMD 

LDX DESCRA 
STX CUCHAR 
LDX #INFCB 
FMTFCB 

TST FCBSTA,X 
BNE FILERR 


get program name to chain in 


back up to first token 
point to FCB 

set name, drive into FCB 

error? 

if so, quit 


CHAIN 

» 


bring in new program 


* CHAIN never returns 

* it will either start new program or give 

* error message and return to system 

» 


This next example illustrates the active-FCB chain process. It will 
print on the console the filename of every active FCB in the system. 

LDX FCBCHN get chain header 

BEQ DONE if=0, no active FCBs 

* 

LOOP LDA A #$0D 

STA A FCBNAM+12,X put c.r. after name 
PSHX save pointer 

LDX FCBNAM,X point to name field 

PRTMSG 

PULX recover FCB pointer 
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LDX FCBNFB,X get chain pointer 

BNE LOOP if not=0, loop 

x 

DONE RTS 

This example is the actual code used by the FMTFCB SVC in CP/68. It 
illustrates the use of NXTOK in parsing a line of text. It also 
illustrates how register data is passed on the stack to CP/68 SVCs. 

FMTFCB TSX 

LDX UXH,X point to FCB 

CLR FCBSTA,X clear status 

CLR FCBDRV,X default drive=0 

NXTOK get a token (assume CUCHAR init.) 

LDA B RC check RC 

CMP B #3 number? 

BNE PARS2 no 

x 

TST VALUE valid drive no.? 

BNE PARS1 no 

x 

LDA A VALUE+1 valid drive no.? 

CMP A #3 (0,1,2,3) 

BHI PARS1 not valid 

x 

STA A FCBDRV,X init. drive number 

BRA PARS1A 

x 

PARS1 TSX 

LDX UXH,X point back to FCB 
LDA A #21 return error code 
STA A FCBSTA,X 
CLR VALUE 

CLR VALUE+1 return no value 
RTS 

x 

PARS1A NXTOK get token from command line 

LDA B RC check RC 

CMP B #•: colon? 

BNE PARS1 if not, error 

x 

NXTOK get token 

LDA B RC check RC 

PARS2 CMP B #1 unambig. name? 

BEQ PARS4 yes, good 

x 

PARS3 TSX 

LDX UXH,X point to FCB 

LDA A #21 

STA A FCBSTA,X return error code 
RTS 

x 
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PARS4 

LDX DESCRA 

point to name 



STX SAVEX 

save it in temp. 

loc. 


LDA A DESCRC 

get length of name 


STA A SAVEA 

save it in temp. 

loc. 


NXTOK 

get a token 



LDA B RC 

check RC 



CMP B 

period? 


* 

BNE PARS3 

if not, error 



INC SAVEA 

count the period 

in length 


NXTOK 

get a token 



LDA B RC 

check RC 



CMP B #1 

unambig. name? 


* 

BNE PARS3 

if not, error 



LDA B DESCRC 

get ext. length 



ADD B SAVEA 

get total length 



TSX 




LDX UXH,X 

X points to FCB 



LDA A #FCBNAM 




ADDAX 

X points to FCBNAM 


PSHX 

set up for FMTS 



LDX SAVEX 

point to name 



PSHX 




FMTS 

format file name 



INS 




INS 

clean stack 



INS 




INS 




TST B 

error check 


# 

BNE PARS3 



* 

RTS 



SAVEA 

RMB 1 

temp, locations 


SAVEX 

RMB 2 
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Part 3 


Description of Routines 

****•••****••**«*«»•*•* 


INTRODUCTION 


The CP/68 operating system consists of a memory-resident part and 
transient files which are loaded into memory when needed. The various 
transient files overlay each other, since only one is ever in use at a 
given time. The resident part occupies memory from 0100 hex to about 2000 
hex. The transients load starting at 2000 hex and occupy no more than 4 K 
bytes each (up to 3000 hex). A part of base-page is also used (a 
description of these locations is given elsewhere in this book). 

The resident portion of CP/68 consists of five parts: 


BIOS- 

CLI- 

DREAD- 

SFIO- 

DRIVERS- 


the Basic I/O System 
Command Line Interpreter 
Directory Read 
Sequential File I/O 
Disk Drive handlers 


There are nine transient commands: 


ASSIGN- 

B00T- 

DELETE- 

INIT- 

LINK- 

PIP- 

SECURITY- 

SET- 

STATUS- 


make device assignments 
bootstrap system 

delete a file (part of this command is resident) 
initialize a new disk 
link a system file for BOOT 
Peripheral Interchange Program 
manipulate access code of files 
manipulate parameters of CON and LPT devices 
display present device assignments 


In addition to these commands, some disk systems require a formatter 
program. 


FORMAT- format a soft-sectored disk 


Also included in this book is the Random-Access file package. This 
transient package of subroutines provides the facilities for random- 
access file manipulation under CP/68. 
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Resident Routines 

a###***#**#**##*# 

BIOS (Basic I/O System) 

The BIOS package consists of the software-interrupt handler (SWIHDR) 
and a set of routines which are called from it. SWIHDR is the only entry 
point within CP/68; it vectors all requests for system services to their 
appropriate handler in the system. The system must vector SWI 
instructions to SWIHDR to enable CP/68 to function. SWIHDR accesses the 
byte following the SWI instruction to determine the desired system 
operation. Invalid bytes (CP/68 has 53 valid operations) are vectored to 
a monitor location trap. Valid bytes are used to index the dispatch table 
(DSPTAB) to find the 16-bit offset of the system handler. A subroutine 
jump is made to the handler, passing all the registers on the stack. (SWI 
placed them there) Upon return, the return address is incremented to skip 
the operation byte and an RTI instruction returns to the caller. 


Extended Instructions in BIOS 


BIOS contains a set of system operations which effectively extend 
the instruction set of the 6800 to include many useful capabilities from 
the 6809 set. These instructions are described elsewhere in this manual. 
They are simply listed here. 


PSHALL 

push all registers 

PULALL 

pull all registers 

TXAB 

transfer X to A,B 

TABX 

transfer A,B to X 

XABX 

exchange X and A,B 

PSHX 

push X 

PULX 

pull X 

ADDABX 

add A,B to X 

ADDXAB 

add X to A,B 

ADDAX 

add A to X 

ADDBX 

add B to X 

SUBABX 

subtract A,B from X 

SUBXAB 

subtract X from A,B 

SUBAX 

subtract A from X 

SUBBX 

subtract B from X 

INDEX 

X=X + A * B 

MUL8 

A,B = A * B 

MUL16 

A,B,X = A,B * X 

DIV16 

A,B = A,B / X (remainder in X) 

MOVC 

move a character string of given length 

CMPC 

compare character strings 

CMWC 

compare character strings with wild-card matches 

MOVS 

move a character string with 04 hex terminator 
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FMTS (Format a filename string) 


This routine takes a filename string as might be input from the console 
and formats it into the required CP/68 format. CP/68 wants filenames in 
the form: 

NAME: 8 characters 

DOT: period 

EXTENSION: 3 characters 

FMTS is called with the addresses of the input and output strings on 
the stack and the length of the input string in the B accumulator. It 
fills the output string space with blanks (20 hex) and places the dot in 
the 9th character position. It then moves the name and extension from the 
input string to the output string. It checks the name and extension for 
validity as it goes, it also checks for wild-card characters. The B 
accumulator returns a status code as follows: 

00 hex unambiguous, valid name 
01 hex ambiguous, valid name 
02 hex invalid name 


DISPATCH TABLE (DSPTAB) 


This table contains the 16-bit signed offsets of each of the CP/68 system 
routines relative to the SWIHDR handler. Note that $FFFF is -1 in 16-bit 
binary. The somewhat strange-looking form of the table entries is 
required since the assembler does not allow unary operators or 
parentheses in address expressions. For example, *-@PSHAL*$FFFF , could 
be re-written as -(#-@PSHAL). Note that DSPTAB is also defined as an 
offset from SWIHDR. 


EQTAB (Equipment table) and PDTAB (Physical Device table) 


These tables are described in detail elsewhere in this book. They are 
used by the I/O handler routines, the ASSIGN, and the STATUS transients. 
Together, they serve to vector I/O requests to the system to the required 
device handler. 
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IOHDR (I/O Handler) 


This is the central handler for CP/68 I/O requests. It is called with the 
address of a control block in the index register. IOHDR calls PDSRCH to 
look through PDTAB for the handler address of the logical device named in 
the control block. It then calls the handler. Handlers are called with 
the address of the control block in A,B. If the device name is invalid, 
IOHDR returns a status of 80 hex which indicates that no such device 
exists. 


PDSRCH 


This subroutine is used by IOHDR to access the physical device table. It 
is called with the address of the control block in the index register. A 
linear search is performed through PDTAB. If the device name is found, 
PDSRCH uses the address in PDTAB to point to the EQTAB. There it loads 
either the input or output handler vector and stores it into the control 
block. A carry-clear on return indicates that the name was found. A 
carry-set is returned if the name was not found. 


Logical Device Handlers 

These routines handle the input and output operations for each of 
the CP/68 logical devices. Each handler is entered with the address of 
the control block in A,B. They return that address in the index register. 


NULL 


The null device simply moves the control block address to the index 
register and returns. 


INLIN (line-oriented input) 


This routine handles lines of data from console-type devices. It handles 
tasks such as fielding "line-delete” and "back-space". It handles echo 
based on the SET "DX" parameter. It provides the CP/68 input prompt. It 
also outputs a linefeed for each carriage return. 

Calls: INCON, 0UTC0N 
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OTLIN (line-oriented output) 


This routine handles output of lines to console-type devices. SET 
parameters such as the null count (NL), line width (WD), paging (DP), 
ejects (EJ), and pause (PS) are handled in this routine. Detection of a 
break (any key struck during output) is provided in this routine. This 
code assumes an ACIA-driven device. The address of the ACIA is derived 
from the Equipment table. 

Calls: INCON, OUTCON 


INCON 


This routine performs the actual handling of the console ACIA for input. 
It is called with the index register holding a buffer address. This value 
is preserved in INCON. The address of the control block is passed on the 
stack. INCON uses this address to access the EQTAB to get the actual ACIA 
address. INCON strips the parity bit and returns the character in the A 
accumulator. INCON will wait for a character. 


OUTCON 


This routine performs the actual handling of the console ACIA for output. 
It preserves the index and B registers. It uses the address of the 
control block from the stack to access EQTAB which gives it the ACIA 
address. The A accumulator passes the character to be output. 


INRDR (line input from papertape reader) 


This routine handles input from the papertape reader (PTR) device. It 
issues the X-ON (11 hex) character to start the reader and uses the X-OFF 
(13 hex) to turn it off at the end of the line. Nulls (00 hex) are 
swallowed. 

Calls: RDRIN, OUTPCH 
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OTPCH (line output to papertape punch) 


This routine handles line output to the papertape punch (PTP) device. It 
appends a linefeed (OA hex) and 4 nulls to each line. 

Calls: OUTPCH 

RDRIN 


This subroutine handles the actual input from the ACIA driving the 
papertape reader. It is identical to INCON except for the stripping of 
the parity bit. 


OUTPCH 


This subroutine handles the actual output to the ACIA driving the 
papertape punch. It is identical to OUTCON. 


OTLPT (line output to lineprinter) 


This routine outputs a line to the lineprinter device. It assumes a PIA- 
type interface. The SET parameters for page width (LWD) and page depth 
(LDP) are handled in this subroutine. OTLPT issues a formfeed (OC hex) to 
space pages. It automatically adds a linefeed for each line. 

Calls: OUTLPT 


OUTLPT 


This subroutine actually handles output to a PIA port. It preserves the 
index and B registers. The address of the control block from the stack is 
used to access EQTAB to get the PIA address. The character to be output 
is passed in the A accumulator. An acknowledgement signal is expected 
from the device. 

The rest of BIOS is a set of jumps to the other routines forming 
CP/68. These jumps are necessary for SWIHDR to vector to separately 
assembled modules. (CLI, Directory read, Sequential File I/O, and Disk 
Drivers) 
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Command Line Interpreter (CLI) 


The CLI is the heart of CP/68. All command processing passes through 
it. It contains the routines that load transients and programs, that save 
memory onto disk, that parse command lines, etc. 


Command Table (CMDTAB) 


This table contains all the commands directly recognized by CP/68. Each 
table entry consists of the first three characters of the command name 
and the address of the command handler. Hence, all CP/68 command names 
can be abbreviated to their first three characters. A zero marks the end 
of the table. 


Character Table (CHRTAB) 


This table is used by the parsing routines (NXTOK) to evaluate a 
character for the type of token it could be in. Characters from the space 
(20 hex) to underline (5F hex) in the ASCII set have an entry in the 
table. Each entry is a byte where each bit has a significance as follows: 


Bit 

7 

Alphabetic 

Bit 

6 

Decimal digit 

Bit 

5 

unused 

Bit 

4 

unused 

Bit 

3 

delimiter 

Bit 

2 

Hexadecimal digit 

Bit 

1 

Wild-card character 


A set bit indicates that the character is a member of the class. For 
example, the letter "A" has the entry 82 hex. This means that it is both 
an alphabetic character and a hex digit. Note that the wild-card 
characters are declared alphabetic (81 hex). 


CLI Main loop 


There are two entries to CLI, called COLDST and WARMST. There is a jump 
to COLDST at the beginning of BIOS (start of CP/68). This is the starting 
location of the system. WARMST is the return to the system, and it is 
reached through SWIHDR. COLDST performs the initialization steps for the 
system. The stack pointer is set to the internal stack space. The SUBMIT 
flag is cleared (no SUBMIT in process). The console and TTY ACIAs are 
initialized. The set-up for the CON device is: 

Counter divide- 16 

Word select- 8 bits + 1 stop, no parity 
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Interrupts- 


disabled 


The set-up for the TTY device is: 

Counter divide- 16 

Word select- 7 bits + 2 stop, even parity 

Interrupts- disabled 

The lineprinter PIA is initialized as follows: 

A side: undefined 

B side: output, CB1 active low input, IRQ disabled 

CB2 output 

INITDK is called to initialize the disk hardware. The console 
control block CONRCB is initialized and the start-up banner is printed. 
The header of the active-file chain is initialized. Processing now begins 
the usual CLI loop. 

WARMST also sets the stack pointer and clears the SUBMIT flag. It 
then looks through the active-file chain, closing all files that it 
finds. It then enters the usual CLI loop. 

WARM3 marks the start of the command-processing loop. First, the 
four free-space headers are cleared. Now a command line is input using 
GTCMD. This line might come from the console or from a SUBMIT file. GTCMD 
automatically parses the first token from the line. If it is an ambiguous 
name (wild-cards), it is a format error. If it is a number, it is assumed 
to be the drive number of a filename. Otherwise, it is an unambiguous 
name which might be a command or else a filename on drive 0. 

The command table is searched to determine if the name is a command. 
If the name is found, control jumps the the processor for that command 
which returns to WARM3 when it completes. If the name is not found, or if 
this is a filename not on drive 0, the system routine (LODCMD) brings the 
named file into memory. Since LODCMD does its own parsing of file nam es, 
the pointers are first returned to the start of the command line. If a 
transfer address was loaded, control jumps to that address. If no 
transfer address was found, or after the loaded process returns, control 
returns to WARM3 for a new command. 

Calls: LODCMD 


PRTMSG 


This routine prints a message on the console and is used by all the CP/68 
routines for printing error messages and prompts. It is called with the 
address of the text string in the index register. The string must be 
terminated with either a carriage return (0D hex) or a string terminator 
(04 hex). The carriage-return causes an automatic linefeed, the string 
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terminator does not 


PRTERR 


This routine prints a formatted error message on the console* It is 
called with the address of a control block in the index register* It 
tests the status byte in the control block for error conditions. If there 
was no error, it prints nothing. If the status byte is nonzero, it 
converts the byte to hex and stores it in the error message field DERNUM. 
The device name is taken from the control block and stored in DEVNAM. 
Finally, the error message is printed. 


GTCMD 


GTCMD is called to input a line of text from the user. Based on the 
SUBMIT flag SUBFLG, the line might come from the console or from an open 
SUBMIT file. If SUBFLG is cleared, GTCMD reads a line from the console. 
If SUBFLG is set, GTCMD reads a line from the open SUBMIT file, using the 
file-control block SUBFCB. If reading from a file, the special characters 
ff & M and 04 hex (control-D) are processed. The control-D indicates the end 
of the SUBMIT file; the file is closed, SUBFLG is cleared, and a line is 
input from the console. The "& Tf indicates diversion in a SUBMIT file, one 
line is taken from the console without upsetting the file or SUBFLG. No 
matter where the line came from, GTCMD always goes into the parsing 
routine NXTOK to find the first token on the line. 

Calls: NXTOK 

Flags: SUBFLG 


NXTOK (parsing tokens) 


This routine performs the parsing function on a CP/68 command line. Each 
time it is called it determines the next lexical token of the command 
line. There are six types of tokens which are recognized: 

Multi-character strings- Unambiguous name 

Ambiguous name 
Number 

Single characters- Delimiter 

Carriage return 
Error (undefined) 

NXTOK uses the pointer CUCHAR to point to the starting point on the 
line to begin parsing. NXTOK moves CUCHAR to point just beyond the end of 
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the present token. NXTOK returns four values for each token. DESCRA is a 
pointer to the first character in the token. DESCRC is a count of the 
length of the token. RC is a code for the type of token. CLASS is a code 
for major classification of the token. 

NXTOK first skips over any blanks up to the first non-blank 
character. If the character is less than 20 hex, it is either a carriage 
return or undefined. If it is greater than 5F hex, it is undefined. This 
means that lower-case characters are not recognized. Next, NXTOK calls 
GCHRTB which looks up the character in CHRTAB. If the character is 
alphabetic, NSCAN is called to parse the name. If the character is a 
decimal digit, DSCAN is called to parse the decimal number. If the 
character is neither, and it is not a delimiter, it is an error. If it is 
a delimiter, NXTOK checks for a character. If found, HSCAN is called 
to parse a hexadecimal number. Otherwise, the delimiter token is 
returned. 

Calls: GCHRTB, NSCAN, DSCAN, HSCAN 


DSCAN 


This routine parses a decimal string. It looks at characters from the 
command line one at a time until a non-decimal digit is found. The 
pointers are decremented to the last decimal digit and it is checked for 
length (since CP/68 works with 16-bit numbers, it can accept nothing 
larger than 65535)* CVDB is called to convert the decimal string into 
binary which is returned in VALUE. 

Called by: NXTOK 

Calls: GCHRTB, CVDB 


NSCAN 


This routine parses an alphanumeric string. It looks at characters from 
the command line one at a time until a non-alphanumeric character is 
found. The pointers are then decremented to point to the last 
alphanumeric character in the string. The B accumulator is used to 
indicate if a wild-card character was found in the name string. 

Called by: NXTOK 

Calls: GCHRTB 
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HSCAN 


This routine parses a hexadecimal number as indicated by a leading dollar 
sign ($). It looks at characters from the command line one at a time 
until a non-hexadecimal digit is found. The pointers are then decremented 
to point to the last hexadecimal digit in the string and the length is 
checked (since CP/68 can accept numbers up to $FFFF). CVHB is called to 
convert the hex string into binary which is returned in VALUE. 

Called by: NXTOK 

Calls: GCHRTB, CVHB 


GCHRTB 


This routine accepts a character in the A accumulator and uses it to 
index the character table CHRTAB. The entry from the table is returned in 
the A accumulator. 

Called by: NXTOK, NSCAN, DSCAN, HSCAN 
Tables: CHRTAB 


CVHB 


This routine converts a hexadecimal string into binary. On entry, DESCRA 
points to the start of the string and DESCRC is the number of characters 
in the string. It returns the 16-bit unsigned binary value in the index 
register. 

Called by: HSCAN 


CVDB 


This routine converts a decimal string into binary. Its calling sequence 
is identical to CVHB. 

Called by: DSCAN 
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Command Processing routines 


All command processing routines are called as subroutines from the CLI 
loop. 


JMPCMD 


This routine processes the JUMP command. It uses NXTOK to parse the jump 
address. It removes the return address (JMPCMD was called as a 
subroutine) from the stack and executes a jump to the address specified 
in the command line. If the routine jumped to executes an RTS, it will 
return to the CLI loop. A "safer” return would be to issue a WARMST call* 


Transient Command Processor 

The set of CP/68 commands processed by transients: 

ASSIGN, BOOT, DELETE, LINK, PIP, SECURITY, SET, STATUS 

must load the required file into the transient space. This is 
accomplished by using a "dummy command” which effectively forces the 
filename of the transient command to become the command line. LODCMD is 
called to bring the transient into memory. For the transients that 
require it, the address of PDTAB is passed in the A and B accumulators. 

Calls: LODCMD 


SUBCMD (SUBMIT command processor) 


This routine processes the SUBMIT command. It uses FMTFCB to parse a 
filename from the command line into the SUBMIT FCB (SUBFCB). Blank 
expansion is turned on and the file is opened. The filetype is checked to 
insure that the file is a text file. The SUBMIT flag is set, indicating 
to GTCMD that lines should now come from the file, not the console. 
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SAVCMD (SAVE command processor) 


This routine processes the SAVE command. It first initializes the control 
block SAVFCB as a type 0 file. FMTFCB is used to parse the filename into 
SAVFCB. The starting address is then parsed and saved in SAVEX. The 
ending address is parsed and saved in SAVEX1. If this is the end of line, 
then no transfer address is desired. If there is a delimiter, then a 
transfer address is parsed, the filetype is made 1, and a transfer- 
address block is written to the file. Next, data records consisting of 
256 data bytes each are written out to the file. When the ending address 
is reached, the last data block is written out and the file is closed. 


LODCMD (LOAD command processor) 


This routine loads a file into memory. It processes the LOAD command and 
is used by the CLI loop and the transient command processor as well. It 
uses FMTFCB to parse the filename and then uses LOADB to actually load 
the file into memory. 

Called by: CLI loop, Transient processing, INICMD 
Calls: LOADB 


LOADB 


This routine actually loads a memory-image file (produced by SAVE) into 
memory. The file must be type 0 or 1 (memory-image). The load process 
opens the file and looks for either data blocks or transfer address 
blocks. Data blocks contain their load address, so the following data is 
stored into the indicated address. Transfer address blocks store their 
address into VALUE. Hence, the last transfer address found in the file 
will be used. 

Called by: LODCMD, CHAIN 


RENCMD (RENAME Command processor) 


This routine processes the RENAME command. FMTFCB is first used to put 
the old filename into SAVFCB. SFILE is called to search the directory for 
this file. If found, the access code is checked to see whether this file 
is rename-able. If so, the second filename (the new one) is parsed. Note 
that the second filename can have no drive number, since the first drive 
number is assumed. Pointers to the directory entry of the old file are 
stored in SAVFCB. SFILE is called with the new filename to insure that it 
does not duplicate an existing name. If there is no duplication, the 
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directory entry for the old filename is re-accessed and the new name 
field is written into it. 

Calls: SFILE 

INICMD (INITIALIZE Command Processor) 


This routine processes the INITIALIZE command. It parses the drive number 
and checks it for validity. LODCMD is used to bring the transient code 
for INIT. into memory. The drive number is passed in the A accumulator 
and control is given to the transient code. When it is complete, it 
returns to the CLI loop. 

Calls: LODCMD 


DIRCMD (DIRECTORY Command Processor) 


This routine processes the DIRECTORY command. It begins by formatting 
ALLFIL into a temporary BUFLIN. ALLFIL is a wild-card specification which 
matches all filenames. The lineprinter flag LPTFLG is cleared to direct 
output to the console. A check is made for the lineprinter switch /L . If 
found, the lineprinter flag LPTFLG is set. Otherwise, DIRCMD looks for a 
drive number. If a number is found, it is checked for validity and if it 
is valid it is stored in SAVEA. Next, DIRCMD looks for a file 
specification. This file specification may contain wild-cards. If a file 
specification is found, it is formatted into BUFLIN. The number of 
sectors used (NSEC) is cleared. If LPTFLG is set, the output is re¬ 
directed to the LPT device. The drive number is recovered from SAVEA and 
converted to ASCII. The header messages are printed. The directory of the 
desired drive is opened. 

DIRCMD now loops through each directory block on the given disk. It 
compares each file on the disk with the name in BUFLIN. If they do not 
match (including wild-cards), DIRCMD looks at the next file in the 
directory. If a match is found, the data from the directory block is 
formatted into a string for output. The string is printed and DIRCMD 
looks at the next file. When the end of the directory is found, the 
number of sectors used (the sum of the number of sectors of each file 
which matched) is converted to ASCII and the finishing message is 
printed. 

Imbedded in DIRCMD is a routine called CVBTD. This routine converts 
a 16-bit unsigned binary number to ASCII. The number is passed in the A 
and B accumulators. The address of the place to form the ASCII text is 
passed in the index register. CVBTD generates five characters. 
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CHAIN 


This routine provides CP/68 the facility to load and run a transient file 
from an executing program. It works by moving the necessary information 
from the user's FCB to the system SAVFCB. The user's FCB address is 
passed in the index register. By moving to SAVFCB, the new program can 
overlay the user's FCB. CHAIN calls LODCMD to bring the new file into 
memory. If a transfer address is found in the new file, control jumps to 
it. Otherwise, control returns to the CLI loop. 

Calls: LODCMD 


SEMPTY 


This routine is used to search a disk directory for an empty slot. It 
looks through the directory for either a directory block with a blank as 
its first character (indicates a deleted file) or the end of the 
directory. If a usable directory block is found, SEMPTY returns a status 
of 0. If no usable block is found, a status of 1 is returned. SEMPTY uses 
a system control block SYSFCB. It is called with the drive to search in 
the A accumulator. It returns the pointers to the directory block in 
SYSFCB. (FCBTRK, FCBSCT, and FCBIND) The status is returned in FCBSTa. 

Called by: OPEN (sequential file I/O) 


SFILE 


This routine searches a disk directory for a given, non-ambiguous file. 
It is called with the address of a control block in the index register. 
This FCB contains the drive and filename of the file to be searched. 
SFILE returns status in the supplied FCB. A status of 0 indicates the 
file was found. A status of 1 indicates the file was not found. FCBIND in 
the supplied FCB points to the directory block. SFILE uses SYSFCB to 
manipulate the directory. 

Called by: OPEN, CLOSE (sequential file I/O), RENCMD, DELETE 
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DELETE (Resident part of DELETE command) 


This routine handles the removal of a file from a disk. It is called with 
the address of an FCB in the index register. This FCB contains the 
filename and drive of the file to be deleted. First, SFILE is called to 
locate the file in the directory. The access code is checked to see if 
this file may be deleted. If so, all the active FCBs are checked to see 
if there are any open files on this disk. If there are, no file deletes 
may be performed on the disk, since this might corrupt the linkages of 
the sectors. If there are no active files on this disk, the directory 
entry of the file is read in. The first and last track/sector pointers 
are saved. A blank is inserted into the name field in the directory. The 
present header of the free-space list on this disk is saved. The first 
track/sector of the file becomes the head of the free-space list. The 
last track/sector of the file is linked to the old free-space header. 
This puts the sectors from the deleted file back onto the free-space 
list. The free-space sector is updated to match this. 

Calls: SFILE 


FMTFCB 


This routine parses a file specification from the command line and places 
the result into a supplied FCB. The address of the FCB is passed in the 
index register. The pointer CUCHAR indicates the beginning of the file 
specification. FMTFCB first looks for a drive number. If none is found, 
drive 0 is assumed. If a number is found, it is checked for validity. 
FMTFCB expects an unambiguous name, (no wild-cards) If a syntax error is 
found while parsing, 21 hex is returned in the FCBSTA field of the FCB. 


DIRECTORY-READ Routines 

This set of routines provides the means to read and change a disk 
directory under CP/68. It consists of three entries: OPEND, GETDR, and 
PUTDR. A CP/68 directory is a sequence of 32-byte directory blocks stored 
on the first track of the disk. The end of the directory is marked by a 
directory block whose first character is a zero. If the first character 
is a blank (20 hex), this directory block is assumed to have been deleted 
and new files will over-write it. 


OPEND 


This entry opens a disk directory for use. It positions the drive to the 
first track (directory) and reads in the first sector of the directory. 
The first character of the directory sector is tested. If it is zero, the 
disk directory is empty and a status of 01 hex is returned, indicating 
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that the end of the directory was found. If it is not zero, a zero status 
is returned. OPEND is called with the address of a user FCB in the index 
register. The FCB must have the drive number set and the device-type must 
be set to DSK. It returns status information in the FCB. 


GETDR 


This entry reads directory blocks from an open directory. OPEND must be 
called prior to calling GETDR. GETDR moves the pointers to the directory 
32 bytes forward each time it is called. This effectively accesses the 
directory block for the next file on the disk. GETDR will read a new 
sector when it finishes the previous one. It will return a status of 00 
hex if it finds a good file block in the directory. It will return a 
status of 01 hex if it finds the end of the directory. Its calling 
sequence is the same as that of OPEND. 


PUTDR 


This entry updates a directory block that has been found with OPEND and 
GETDR. The changes to the file directory data are made to the copy in the 
sector buffer used with OPEND and GETDR. Calling PUTDR with the address 
of the FCB in the index register will re-write the directory sector into 
the directory, making the desired updates. 


SEQUENTIAL-FILE I/O Routines 

These routines handle sequential files under CP/68. They direct the 
directory-routines and the drivers to form a file-management system. 
There are five routines: OPEN, CLOSE, READ, WRITE, and REWD. Each is 
called with the index register pointing to an FCB. Those routines which 
pass characters (READ, WRITE) use the A accumulator. These routines also 
handle space-compression for text files. 


OPEN 


OPEN prepares files for use under CP/68. It first checks that the file is 
not already open, then it determines whether the file is to be opened for 
input or output. The in/out decision is based on the FCBDTT byte in the 
FCB. 


Input files are checked against the disk directory to see if the 
file already exists. The system subroutine SFILE performs this check. 
Next, OPEN moves the file pointers, type, etc. from the directory to the 
FCB. The first sector of the file is read in; the forward and backward 
sector links are put into the FCB. Finally the FCB is added to the 
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active-FCB chain. 


Output files are processed differently. SFILE is called to check 
that the new filename does not duplicate an already existing file. Next, 
the system subroutine SEMPTY is called to find an available directory 
block for the new file. The FCBNMS (number of sectors), FCBLTS (last 
track/sector), and FCBBAK (back pointers) fields in the FOB are cleared. 
The free-space header for the desired disk is accessed. If it is nonzero, 
this is the track/sector of the next available sector. If it is zero, the 
free-space sector (link sector) is read and the header is updated. The 
free-sector is checked to see that it is not the end of the disk (0,0). 
The FCBFTS (first track/sector) field in the FCB is initialized to the 
free sector and the directory entry is written using PUTDR. The free 
sector is read in and the free-space header is updated to be the next 
available sector. Finally, the FCB is added to the active-FCB chain. 

Calls: SFILE, SEMPTY 


CLOSE 


This routine finishes the processing of a file. First CLOSE checks that 
the FCB is open. If it is found in the active-FCB chain, it is removed 
from the chain. If it was an input file, CLOSE is finished. For output 
files, CLOSE must write out the last sector. It uses SFILE to find the 
directory entry for the file and updates the FCBLTS (last track/sector) 
and FCBNMS (number of sectors) entries. The free-space record is updated. 
This completes the CLOSE process. 

Calls: SFILE 


READ 


This routine gets a byte from an open input file. It checks to see if the 
desired byte is in the sector buffer already. If it isn't, a new sector 
is read in and the forward and backward links are updated; the byte is 
accessed from the buffer. If no space-compression is required, the file 
pointer (FCBIND) is incremented and the data byte is returned. If space- 
compression is required, a test is made of the data byte. If the byte is 
positive (high-order bit is zero), the data byte is returned unchanged. 
If the byte is negative (high-order bit set), the byte is a compressed 
space. The data byte is actually the negative count of the number of 
spaces desired. The data byte is incremented and restored to the buffer 
while a space (20 hex) is returned. When the data byte reaches 00 hex, 
the last space is returned and the file pointers are moved. Until then, 
spaces are returned while the file pointer stays in the same point in the 
sector buffer. 
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WRITE 


This routine writes data bytes to an open disk file. It first checks that 
the file is open for output; next it checks to see if the end of the 
sector buffer has been reached. If it has, the present sector buffer is 
written to the disk. The number of sectors in the file (FCBNMS) is 
incremented; the free-space header is updated, as are the forward and 
backward file pointers (FCBFWD and FCBBAK). A new sector is read in from 
the free-space chain and linked to the file. In either case, the next 
step is to store the data byte into the sector buffer. If no space- 
compression is being done, WRITE is completed. If space-compression is 
being done, and if the data byte is a space (20 hex), the present value 
of the data byte in the file is checked. If it is negative (compressed 
space), the value is decremented (one more space) and restored. If it is 
not negative, a single compressed space (FF hex) is stored into the file. 
This completes WRITE. 


REWD 


This routine rewinds an input file to its starting point. Effectively, 
REWD is a CLOSE followed by an OPEN. 


DRIVER Routines 

These routines provide the interface between CP/68 and the disk 
hardware. Three entries are needed: INITDK, RDSEC, and WTSEC. The exact 
mechanism of these routines depends on the hardware being used. 


INITDK 


This routine performs all necessary initialization required by the disk 
system. This may include initializing peripheral interfaces, setting 
memory flags, calling ROM routines, etc. It is called with no parameters. 


RDSEC 


This routine reads a desired sector from the disk. It is called with the 
address of an FCB in the A and B accumulators. The FCB contains the 
drive, track, and sector pointers. It also contains a pointer to the 
buffer area. The status of the read must be returned in the FCB. It 
should also be returned in the A accumulator. Since these routines are 
called from software interrupts, they must change the stacked-value of 
the accumulator in order to return it. RDSEC must detect disk errors and 
return appropriate error status numbers. 
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WTSEC 


This routine writes a desired sector to the disk. It is called with the 
address of an FCB in the A and B accumulators. The FCB holds the drive, 
track, sector, and sector-buffer pointers. The status should be returned 
in the same manner as RDSEC. 


Transient Commands 

****************** 

ASSIGN Transient Command 

This routine processes the ASSIGN command from CP/68. It re-directs 
a logical device by modifying the physical-device table entry (PDTAB) of 
a given device. PDTAB entries consist of 7 bytes. The first three bytes 
are the name of the device. The next two bytes are a pointer to the 
appropriate entry in the equipment table (EQTAB) where the device handler 
addresses are found. The last two bytes are also a pointer to the EQTAB. 
ASSIGN modifies the first pointer field, but the second pointer is left 
intact so that other routines (such as STATUS) can find the original 
device assignment. 

When ASSIGN is called from the command-interpreter, the address of 
PDTAB is passed in the A and B accumulators. ASSIGN then proceeds to 
parse the command line, obtaining the names of the devices to be 
assigned. The device to be assigned is stored in DEVI, the device to 
which it is being assigned is stored in DEV2. The subroutine PDSRCH is 
used to check the names in DEVI and DEV2 against the names in PDTAB to 
insure that both are valid device names. 

If DEV1=DEV2, the second pointer field of the name is copied into 
the first pointer field of the name. If DEVI is different from DEV2, then 
both names are checked with PDSRCH, and the second pointer field of DEV2 
is copied into the first pointer field of DEVI. Note that even though 
DEV2 may have been re-assigned itself, the second pointer field retains 
the initial value. 

Called by: CLI 
Calls: PDSRCH 
Tables: PDTAB 


PDSRCH 


ASSIGN uses this routine to check device names for validity. It searches 
the physical-device table (PDTAB) for a device name whose address is 
passed in the index register. The end of PDTAB is marked with a zero. 
PDSRCH returns with carry-set if the device was not found, and with 
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carry-clear if the name was found 


Called by: ASSIGN 
Calls: none 
Tables: PDTAB 


BOOT Transient Command 

This routine bootstraps a system file from drive 0 using no system 
support. It assumes that the disk in drive 0 has had a bootable file 
linked on it (See LINK). It is written to be ROMable, with all necessary 
RAM locations in COMMON storage. It also uses its own stack space. 

The first step BOOT performs is to initialize the disk drives. This 
process varies depending upon the hardware requirements. The next step is 
to read in the link sector, (track 0 sector 1) The last six bytes of this 
sector contain special information. 

SECSIZ-6 First track of linked file 
-5 First sector of linked file 
-4 Last track of linked file 
-3 Last sector of linked file 

SECSIZ-2,1 Free-space pointer 

The track/sector pointers define the linked file. 

BOOT loads the desired file into memory just like the system LOADB 
routine does. The marker 16 hex indicates a transfer-address block, the 
marker 02 hex indicates a data block. The loading process continues until 
the last sector of the file (as determined from the link sector) has been 
loaded. The program then jumps to the transfer address read from the 
booted file. Finding a null (00 hex) while searching for a data block 
will also indicate the end of the file and will cause a transfer to the 
start address read from the file. 

Called by: CLI 
Calls: GETBYT, RDSEC 


GETBYT subroutine 


This routine is used by BOOT to read in the desired file. It returns data 
bytes in the A accumulator. When necessary it calls RDSEC to get a new 
data sector from disk. When GETBYT finishes the last data byte of the 
last sector of the file, it jumps to the spot in BOOT which indicates an 
end-of-file condition. 

Called by: BOOT 
Calls: RDSEC 
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RDSEC Routine 


RDSEC is the routine used to read individual sectors from the disk. It is 
called with the desired track in accumulator B, the desired sector in 
accumulator A, and the address of a buffer in the index register. RDSEC 
assumes drive 0. The actual mechanism of RDSEC depends on the hardware 
used to control the disks. 

Called by: BOOT, GETBYT 


DELETE Transient Command 

This transient routine is used in conjunction with the resident 
DELETE code to handle the removal of files from the disk. The resident 
code actual performs the disk update, this transient handles set-up for 
it and also takes care of wild-card names, check-prompting, and other 
tasks. 


DELETE first accepts a filename and tries to format the name into 
its internal SYSFCB. Since there may be wild-cards in the name, a 
temporary buffer called TEMP is used to hold the name. If the name parses 
as a good filename, the next step is to search the desired disk directory 
for a file whose name matches the given name in TEMP. If such a file is 
found, DELETE forms a prompt line with the file name and waits for a user 
response. If the response is "Y", the file is set up for the resident 
DELETE and is then erased from the disk. After the file is erased, or if 
the response was not n Y", the transient continues to search the disk 
directory for further matches. If more are found, they will each be 
prompted in turn. When the end of the directory is found, DELETE will 
prompt for a new filename. Entering an ESCAPE character returns the 
system to the command level. 

Called by: CLI 
Calls: none 


INITIALIZE Transient Command 

This routine builds the necessary data structure for CP/68 on a 
blank disk. Soft-sectored disks must have been previously formatted 
before using this routine on them. 

INITIALIZE first prompts the user that it is ready to initialize a 
disk in a given drive. The drive number is passed in the A accumulator 
from the CLI. If the user responds "Y", the initialization process 
begins. If the response is not "Y", the program returns to the CLI. 

Initialization begins by writing the link sector. The last two bytes 
of this sector are set to point to track 1, sector 1 (the start of the 
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free-space). The remainder of track 0 (directory) is cleared. The rest of 
the sectors on disk (tracks 1 and above) are linked together into a free- 
space chain. The first two bytes of each sector point to the next sector. 
The third and fourth bytes point back to the previous sector. The 
remainder of the sector is cleared. The forward pointer of the last 
sector on the disk points to 0,0. The sectors need not be contiguous. A 
table called TBL is used to initialize the disk to an interleave pattern 
determined to provide the fastest access times for files. This table is 
entered with a logical sector number, it returns the physical sector 
number on the given track. The subroutine GETSC performs the lookup in 
TBL. The subroutine WRTBLK is used to write data sectors onto the disk. 
If a disk error occurs, the initialization process is aborted with an 
error message that indicates the sector and track of the bad spot on the 
disk. 

Called by: CLI 
Calls: GETSC, WRTBLK 


GETSC 


This subroutine converts a logical sector number into a physical sector 
number, using an interleave table TBL. 

Called by: INITIALIZE 
Tables: TBL 


WRTBLK 


This subroutine writes a data sector onto the disk. An internal control 
block FCBSPC is used to direct the writing. Errors are trapped to WRTERR 
which outputs the track, sector, and error numbers in hex. 

Called by: INITIALIZE 


LINK Transient Command 

This routine is used to set the pointers in the link sector to point 
to a desired file. This is typically a CP/68 system file, but it can be 
any binary file which is to be bootstrapable. 

The first step is to prompt the user for a file name. The name is 
parsed to be sure that it is a valid, non-ambiguous file name. LINK then 
looks up the file name in the disk directory. If found, the first and 
last tracks and sectors are recovered from the directory and placed in 
the internal SYSFCB. If the file is not found, or if it was not a valid 
filename, LINK gives an error message and returns to the CLI. If found, 
the link sector of the disk is read, the pointers updated to those from 
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the directory, and the link sector is re-written to the disk. It then 
returns to the CLI 

Called by: CLI 


PIP Transient Command 

This routine handles all forms of data manipulation from one device 
or file to any other device or file. PIP (Peripheral Interchange Program) 
handles such diverse tasks as file concatenation, disk copy, binary-to- 
MIKBUG conversion, etc. It has several sections which perform different 
operations. 


DEVTAB 


This table lists the various devices supported by CP/68 and has the 
addresses of handlers for them. This differs from PDTAB and EQTAB in that 
PIP uses character-by-character I/O, not line-oriented I/O as used in the 
rest of CP/68. Each entry in DEVTAB consists of 11 bytes. The first three 
bytes are the device name. The rest of the entry is a set of four 
addresses, each two bytes. The first address is a handler for device 
"open". The second address is a handler for device "close". The third 
address is a handler for device character read. The last address is a 
handler for device character write. If one of these addresses is zero, it 
indicates that the device cannot perform the desired operation. (Read 
from line printer, etc.) The end of the table is marked with a zero. 


CHARACTER-ORIENTED DEVICE HANDLERS 

These short subroutines handle the various devices under CP/68 so 
that they can provide character-by-character I/O. The "open" routines 
check that the device is capable of the desired operation. The "open" for 
the lineprinter automatically emits a form-feed (OC hex). The "close" 
routines for devices like the paper-tape punch automatically add control- 
D (04 hex) to indicate end-file. The "read" routines for devices like the 
paper-tape reader and teletype check for control-D and return end-file 
status when it is found. All the routines are called with the address of 
a control block (one of the internal FCBs) in INHND for input and OUTHND 
for output. 


DLKUP 


This subroutine performs the lookup of a device name in DEVTAB. The 
address of the device name is passed in the index register. Carry-set on 
return indicates that the name was not found. Carry-clear indicates that 
the name was found and the address of the table entry is in the index 
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register 


PIP itself 


The main body of PIP parses the command lines and determines the 
necessary processing. The first step is initialization of the input and 
output FCBs. The device is assumed to be disk 0 unless otherwise 
specified. A blank is placed in the first character of the filename 
field. PIP next processes the left side of the command line. If a number 
is found, it is checked for validity as a drive. If an error is found, 
PIP reprompts for another command. Otherwise, the program tries to 
complete the file name parsing. A valid filename is parsed into the input 
OUTFCB. If no number was found, the entry might be a file on drive 0 or a 
device name. DLKUP is used to check whether the entry is a device name. 
If not, the entry is formatted as a file name; if it is, the device name 
is placed in OUTFCB. The address of the device handler is placed in 
OUTHND. 

PIP next looks for a slash (/) that indicates the presence of 
switches. If a slash is found, the switches are checked and appropriate 
flags set. Switches are separated with slashes. Parsing of the output 
portion of the command line ends with the equals sign in the line. 

The output portion of the command line could also be a drive 
specification only (number followed by a colon). If this is the case, a 
flag is set to indicate that a form of disk-copy is requested (PIPFLG). 

The input portion of the command line (right of the equals sign) is 
parsed much the same as the output side, except that no switches are 
allowed. Ambiguous filenames (with wild-cards) are allowed if in a file- 
copy (PIPFLG set). 

Once the command line has been parsed, the transfer of data can 
begin. The character-oriented device handlers are used to move data from 
the input device to the output device. Upon completion of the transfer, 
PIP checks the command line for a comma or other delimiter on the right. 
If found, this indicates another input source is to be concatenated. The 
source specifier is parsed and if valid, its data is also transfered. 

I/O errors during transfer are indicated, but the processing 
continues. Note also that since transfers are buffered by the handlers, 
there will be a one line lag between input and output. 

Upon completion of data transfer, PIP reprompts for a new command 
line after issuing a "DONE" message. An ESCAPE character will allow 
return to command level. 
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DTDCPY 


This routine is called when PIP determines that the form 
drive: = drive: 

has been commanded. This routine performs a direct sector-for-sector copy 
from one disk to another. A prompt is issued which indicates the 
direction of copy and gives the user a chance to correct mistakes in the 
command. 


FILCPY 


This routine is called when PIP determines that the form 

drive:= drive: wildcard name 

has been commanded. The wild-card filename is moved into temporary 
storage TMPBUF. The disk directory is searched for filenames which match 
the name. If a match is found, the name is echoed and the user is 
prompted for a response. If the response is "Y", the file is copied. 
After the copy, or if the response was not "Y", further matches are 
sought in the directory. Each match is prompted in turn until the 
directory is exhausted. 


HEXFRM 


This routine converts the internal binary-format of program files into 
MIKBUG or hexadecimal format. It is called when the H switch (HFLAG) is 
set by PIP. 


BINFRM 


This routine converts MIKBUG or hexadecimal-format data into the internal 
CP/68 binary format. It is called when the B switch (BFLAG) is set by 
PIP. 
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SECURITY Transient Command 


This routine is used to change the access code of a given file. It 
first parses the filename passed to it by the CLI. This name is looked up 
in the disk directory. If not found, an error message is returned and the 
CLI is resumed. If the file is found, its directory information is 
retained in the internal SYSFCB. The command line is parsed for a comma 
followed by a number. If found, and if the number is less than 256, the 
number is placed into the directory access entry of the named file and 
the directory is updated. If an error was found, the program simply 
returns to CLI without changing the directory. 

Called by: CLI 


SET Transient Command 

This routine processes the SET command. It manipulates the CONsole 
and LPT parameters in base-page. The set of legal parameter names is 
contained in the table SETAB. Each entry consists of 4 bytes. The first 
two bytes are the 2-character name of the parameter. The second two bytes 
are the address of this parameter. Two bytes are used because not all 
versions of CP/68 place the parameters in base-page. The subroutine 
SETSRC searches this table for the parameter whose name is contained in 
the index register. Carry-clear indicates that the parameter was found in 
the table and that its address is in the index register. Carry-set 
indicates that the name was not found. 

The normal case of SET is PAR=number. In this case, the value of 
"number" is stored at the address recovered from SETAB based on "PAR". 
There are two special cases in SET. If PAR=DX, the appropriate values are 
not numbers but "F" or "H" (full or half-duplex). SET checks for these 
responses and stores FF hex into the DX parameter address for half-duplex 
and 00 hex for full-duplex. If PAR=PS, the appropriate values are "Y" or 
"N" (pause Yes or No). SET checks for these responses and stores FF hex 
into the PS parameter address for pause-off and 00 hex for pause-on. 

Called by: CLI 


STATUS Transient Command 

This routine prints out the present state of logical/physical device 
assignments. It is called with the address of the physical device table 
(PDTAB) in the A and B accumulators. It works by taking the device name 
of an entry in the table and looking at its two address pointers. If they 
are the same, the device has not been re-assigned and so it can be 
printed as 

DEV = DEV 

If the pointers differ, it indicates that a re-assignment has been 


78 


(c) Hemenway Associates, Inc, 1979 



done. PDTAB is searched for an entry whose second address pointer matches 
the first address pointer of our given entry. When found, its device name 
is the one to which the given device has been re-assigned. Therefore, if 
DEVI is the given device name, and DEV2 is the name of the entry whose 
second address matched DEVI's first address pointer, STATUS prints 

DEVI = DEV2 

STATUS performs this operation for all devices in PDTAB and then returns 
to CLI. 

Called by: CLI 
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Part 4 


FORMAT Transient Utility 

•»***•**«**«•*«*•«*«•••* 


Those versions of CP/68 which utilize soft-sectored disks require a 
program which writes the necessary format data onto new diskettes. This 
information must be on the disk prior to initialization. It usually needs 
to be written only once. 

The FORMAT program consists of three parts: the driver, the track- 
build subroutine, and the track-write subroutine. The driver and track- 
build sections are the same for all hardware (on 5-inch disks using 128- 
byte sectors). The track-write section varies for different hardware 
configurations. 


DRIVER 


This routine gets a drive number from the user. It checks this number for 
validity and issues another prompt to the user. The second prompt allows 
the user to change disks or to abort the formatting process. The rest of 
the driver is a loop which calls TRKBLD and then TRKWRT for each track on 
the disk. 


TRKBLD 


This routine builds an image of an entire formatted track in memory 
(TRKBUF). TRKBLD assumes 128-byte sectors, 18 sectors per track, and a 
Western Digital 1771 disk controller. The track format is: 
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sector starts here 


GAP 8 bytes of FF hex 

GAP 7 bytes of FF hex 

SYNC. 4 bytes of 00 hex 

ID-MARK 1 byte of FE hex 

TRACK # 1 byte (track number) 

1 byte of 00 hex 
SECTOR 1 byte (sector number) 

1 byte of 00 hex 

LENGTH 1 byte of 00 hex (128 bytes) 

CRC 1 byte of F7 hex 

GAP 11 bytes of FF hex 

SYNC 6 bytes of 00 hex 

D-ADDR 1 byte of FB hex 

DATA 128 bytes (00 hex) 

CRC 1 bytes of F7 hex 

PAD 1 byte of FF hex end of sector 

(repeat for 18 sectors) 

GAP 400 bytes of FF hex 


Track numbers are set by the driver in a location called TRACK. 
Sector numbers are set in a location called SECTOR. TRKBLD needs at least 
3400 bytes for its track image. 


TRKWRT 


This subroutine is called by the driver to transfer the track image built 
by TRKBLD to the disk. TRKWRT must position the desired drive to the 
desired track. The drive number is found in the CP/68 location VALUE. The 
track number is found in TRACK. After positioning the drive, TRKWRT must 
do a track-write operation. The exact mechanism of this operation depends 
upon the hardware in use. 
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Part 5 


Random-access files 

******************* 


This section discusses the random-file support package provided with 
the CP/68 operating system. You can link it to STRUBAL+ or assembly 
programs which run under CP/68 and which will manipulate random-access 
files. 


WHAT ARE RANDOM-ACCESS FILES? 

Random-access files are a special type of file structure. There are 
two major differences between the normal CP/68 sequential file and the 
random-access file: 

1. Random-access files can perform both input and output 
operations on an open file. Sequential files are opened 
for input or output but never both. 

2. Random-access files can be arbitrarily positioned to 
locations within the file. Sequential files can be 
positioned to their origin via the REWD system call, but 
they cannot be positioned to other locations without 
reading or writing between the starting position 

and the desired position. 

Random-access files are actually a special type of sequential file. The 
random-access file has a data structure written into it which facilitates 
positioning to arbitrary locations. 


PHYSICAL AND LOGICAL RECORDS 

There are two terms which must be differentiated in order to explain 
the functioning of random-access files. The first of these terms is 
physical record. A physical record is the block of data treated as a unit 
by the storage device being used. 

In the case of floppy-disks, the physical record is also called 
sector because it is written (or read) out as a single unit. CP/68 allows 
the user to read and write arbitrary sectors with the IOHDR system call. 
Thus, random-access at the physical record level is provided in CP/68. 
The size of a physical record, however, is fixed by the hardware. This 
imposes severe restrictions on the user, whose data may not fit in the 
required record size. The user desires control over the size of record. 
It is desirable to vary the record size to fit the application. This 
variable-sized record is referred to as a logical record. The logical 
record does not depend on hardwareit is under program control. The 
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manipulation of logical records (hereafter simply called records) is done 
by the routines described in this manual. The routines in this package 
must convert the user's descriptions of logical records into internal 
descriptions in terms of physical records. 


ENTRY POINTS IN THE RANDOM-ACCESS PACKAGE 
There are seven entry points in this package. 


1. CREATE 

2. ROPEN 

3. RCLOSE 

4. RREAD 

5. RWRITE 

6. POSITION 

7. EXPAND 


build a new random-access file 

open an existing random-access file 

close an open random-access file 

read a byte from the current position of a 

random-access file 

put a byte into the current position of a 
random-access file 

move the random-access file pointer to the 
start of a desired record. 

add new records to an open random-access file 


User packages may link with these routines by using their names as 
EXTernals. Alternatively, a vector table is provided at the start of the 
random-access package which has jumps to each of the routines in the 
order given above. Each routine is called with the address of an FCB 
(File-control block) in the index register. The RREAD routine returns the 
byte just read in the A accumulator. The RWRITE routine is passed the 
byte to be written in the A accumulator. 


THE RANDOM-ACCESS FILE-CONTROL BLOCK (FCB) 

The file-control block (FCB) used with random files has five 
additional data fields appended to it, compared to the normal FCB as 
described in the CP/68 Advanced User's Guide. They are: 

FCBRNM 


This 2-byte field holds the number of records contained in the 
file. It must be set by the user when CREATE is called. It is 
set by the system on ROPEN. There is a maximum for this value, 
based on the sector size of the floppy disks in use, and given 
by the relation 


MXRNUM = 20 * (SECSIZ-4) 

where SECSIZ is the number of bytes in a disk sector. If 
SECSIZ=128, this value becomes 2480. For 256-byte sectors, the 
maximum is 5040 records. 
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FCBRSZ 


This 2-byte field holds the number of bytes in each logical 
record. The user must set it when CREATE is called. It is set 
by the system on ROPEN. The record size can be as small as one 
byte or as large as 65535 (FFFF hex) bytes. It is recommended 
that record sizes be kept fairly large—there is a 3-byte 
overhead for each record in the file. 

FCBRCD 


This 2-byte field holds the record number representing the 
current file position. The system initializes it when the file 
is opened (the first record number is 1). The user must set 
this field before POSITION is called. 

FCBPOS 


This 2-byte field holds the present record pointer of the 
current file position. The system intializes it when the file 
is opened. It gives the location within the current record that 
data will be read from or written into. As data is read or 
written, FCBPOS is incremented until FCBRSZ is reached. At 
this point , FCBRCD is incremented and FCBPOS reinitialized. 
Thus, any byte in the file is addressed by its record pointer 
(FCBRCD) and its position within the record (FCBPOS). 

FCBRTB 


In order to rapidly address a record within a file, the random- 
ccess package builds a table of addresses at the time that the 
file is opened. This table is built in the FCB of the file and 
occupies 120 bytes. The table consists of a 2-byte entry for 
each sector of the random-access file index. Hence, the table 
supports up to 60 index sectors per file. This leads to the 
limitation on FCBRNM. 

The following EQUates will address the new FCB fields when used like 
the EQUates defined for the other FCB fields. 

FCBRNM EQU 42 
FCBRSZ EQU 44 
FCBRCD EQU 46 
FCBPOS EQU 48 
FCBRTB EQU 50 

Note that the FCB for a random-access file must be 170 bytes long. 
(The sequential-file FCB required only 42 bytes). 
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DATA STRUCTURES IN RANDOM-ACCESS FILES 


Every random-access file built by CP/68 contains a data structure 
termed an index. This index is itself a sequential file containing 
pointers to the data records contained in the file. Thus, each random- 
access file is two sequential files: an index and the data record. 

The file's first four bytes contain the values of FCBRNM and FCBRSZ- 
-which describe the size of the file and data records. The index follows 
these two values. This index consists of a 3-byte entry; the first byte 
represents the track on which the data record begins, the second 
represents the sector on which the data record begins, and the third byte 
represents the position of the record's first data byte within the 
sector. The pointers are written sequentially as their data records are 
allocated during the CREATE processing. The end of the index is marked by 
a pointer containing all zero values. The index is padded with nulls 
(zero values) to fill out the last sector. 

Data records begin on the next sector of the random-access file. 
They are simply a sequence of bytes FCBRSZ long and initialized to zero 
during the CREATE processing. There are no end-of-record marks; the end 
of one record is contiguous with the start of the next sequential record. 
Reading or writing past the end of a data record will automatically spill 
over onto the next data record. The RREAD and RWRITE routines will update 
the pointers FCBRCD and FCBPOS to indicate the current file position. The 
POSITION routine can be called at any time to move the file pointers to 
the start of a desired record. 


RANDOM-ACCESS FILE ROUTINES 


CREATE 


This routine builds the structures for a new random-access file on disk. 
The user must provide a random-access FCB (170 bytes long) with the 
drive, filename, record size, and number of records set up. (FCBGDT=DSK, 
FCBDRV, FCBNAM, FCBRSZ, FCBRNM) A new file will be created with an index 
for each record. Each record will be cleared to zero. The filetype of the 
file will be set to 02. All random-access files disable space- 
compression. CREATE is called with the address of the FCB in the index 
register. It returns status information in FCBSTA of the user FCB. CREATE 
destroys the contents of the A and B accumulators and the condition 
codes. It leaves the index register intact. A CREATEd file is not open— 
it must be opened by a call to ROPEN before it may be accessed. CREATE 
may take a long time to build a large random-access file, since it must 
write the index as well as each data record in the file. 
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ROPEN 


This routine prepares a previously CREATEd file for use. It is called 
with the address of a user FCB in the index register. The drive and 
filename must be set up by the user (FCBGDT=DSK, FCBDRV, and FCBNAM). It 
reads FCBRNM and FCBRSZ from the file and places them in the user FCB 
(which must be 170 bytes long). It also stores the filetype (must be 02), 
access code, first track and sector (T/S), last T/S (FCBTYP, FCBACS, 
FCBFTS, and FCBLTS) fields into the FCB. The file pointers (FCBRCD and 
FCBPOS) are initialized to point to the first record in the file. The 
ROPEN routine also reads the file index, building a table (FCBRTB) in the 
FCB containing the track and sector of each sector of the index. All 
unused table entries are cleared. The process of building this table may 
take many seconds for a file with many data records. ROPEN destroys the A 
and B accumulators and the condition codes; it returns the index register 
intact. Error status is returned in the FCBSTA field of the user FCB. 


RCLOSE 


This routine closes the file described by the user FCB whose address is 
passed in the index register. Any pending output is completed before the 
FCB is de-allocated. RCLOSE should only be used on random-access files. 
(type=02) It destroys the A and B accumulators and condition codes; the 
index register is returned intact. Error status is returned in the FCBSTA 
field of the user FCB. 


RREAD 


This routine reads a data byte from a random-access file. It is called 
with the address of the user FCB in the index register. The data byte 
read is returned in the A accumulator. RREAD reads sequentially from the 
current file position defined by FCBRCD and FCBPOS. If the last operation 
performed on the file was writing, RREAD will finish that operation 
before reading. Subsequent calls to RREAD will access sequential data 
bytes. RREAD destroys the B accumulator and the condition codes; the 
index register is returned intact. Error status is returned in the FCBSTA 
field of the user FCB. If a read error occurs, RREAD will return a null. 
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RWRITE 


This routine writes a data byte into a random-access file. It is called 
with the address of the user FCB in the index register and the byte to be 
written in the A accumulator. The data byte will be written at the 
current file position defined by FCBRCD and FCBPOS. Subsequent calls to 
RWRITE will write sequential data bytes. RWRITE destroys the A and B 
accumulators and the condition codes; the index register is returned 
intact. Error status is returned in the FCBSTA field of the user FCB. 


POSITION 


This routine moves the current file position to the start of a desired 
record in the file. It is called with the address of a user FCB in the 
index register. The desired record is set in the FCBRCD field of the FCB. 
POSITION will initialize FCBPOS when the desired record is found. If the 
last operation performed on the file was writing, the last write will be 
finished before the file position is changed. POSITION destroys the A and 
B accumulators and the condition codes; the index register is returned 
intact. Error status is returned in the FCBSTA field of the user FCB. 


EXPAND 


This routine adds new records to an existing, open, random-access file. 
EXPAND is called with the address of a user FCB in the index register. 
The number of new records desired is set in the FCBRCD field of the user 
FCB. The new records will have the same size (FCBRSZ) as the others in 
the file. EXPAND will close the file after the new records have been 
appended. None of the old records will be affected by the EXPAND process. 
The new records are added after all the old ones. A file may be EXPANDed 
many times. EXPAND destroys the A and B accumulators and the condition 
codes. The index register is returned intact. Error status is returned in 
the FCBSTA field of the user FCB. Adding many records to a file may take 
a long time. 


NEW ERROR CODES FOR RANDOM-ACCESS FILES 

The random-access routines trap all the same file errors as the 
sequential routines do. In addition, they trap four new errors that are 
specific to random-access operations. They are: 

OB BAD RECORD SIZE PARAMETER 

The value specified for FCBRSZ was zero. 

OC BAD RECORD NUMBER PARAMETER 

The value specified for FCBRNM was zero or greater 
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OE 


than the MXRNUM for the system sector size. 

BAD FILE TYPE 

The file specified is not random-access type. (02) 


OF BAD POSITION PARAMETER 

The value specified for FCBRCD lies outside the file. 
(The last data byte of the last data record has been 
written or read.) 
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NOTES AND WARNINGS 


I. 

Random-access files contain track/sector information in their 
indices. Hence, rearranging their sectors on the disk will 
corrupt the indexing and destroy the file. Disks which have 
random-access files on them should not be copied using the 
packing (drive:=drive:*.*) PIP command. Such disks should be 
copied exactly, sector-for-sector, using the nonpacking PIP 
copy command. (drive:=drive:) Using PIP to transfer a random- 
access file from disk to disk will corrupt the new file, 
making it worthless. 


II. 

The FCBDTT field of the FCB, which was used in sequential file 
handling to specify input or output, is under system control 
when working with random-access files. It should not be used 
by the programmer. 
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EXAMPLE OF THE USE OF CP/68 RANDOM-ACCESS FILE ROUTINES 


The following program illustrates the use of random-access 
file routines under CP/68. It allows exercise of all the CP/68 
random-file operations. 


NAM TESTRND 

« 

* EXERCISE PROGRAM FOR RANDOM-ACCESS FILES IN CP/68 

ft 

* 'O' OPEN FILE (ONLY ONE FILE OPEN AT A TIME) 

« »C» CLOSE FILE 

» 'B' BUILD A NEW RANDOM-ACCESS FILE 
« *R' READ FROM CURRENT POSITION IN FILE 
« (END ON CARRIAGE-RETURN IN FILE) 

« »W' WRITE TO FILE AT CURRENT POSITION 

* (END WITH CARRIAGE-RETURN) 

« 'P' POSITION FILE TO DESIRED RECORD 
« »E' EXPAND CURRENTLY-OPEN FILE 

JMP START 

« 

* DEFINE RANDOM-FILE EXTERNALS 

ft 

EXT CREATE 
EXT ROPEN 
EXT RCLOSE 
EXT RREAD 
EXT RWRITE 
EXT POSITION 
EXT EXPAND 

* 

« DEFINE TEXT BUFFER FOR OUTPUT 

ft 

BUFFER RMB 80 80 CHARACTERS FOR LINE BUFFER 

BUFEND FCB $0D FORCE C.R. ON LINE 

BUFPNT RMB 2 BUFFER POINTER STORAGE 

• 

» DEFINE CP/68 EQUATES 

• 

BASEQU 
FCBDEF 
FCBRNM EQU 42 

FCBRSZ EQU 44 

FCBRCD EQU 46 

FCBPOS EQU 48 

ft 

» LOCAL RANDOM-FCB BLOCK 

ft 

FCBLK RMB 2 
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FCC 

•DSK' 


RMB 

2 


FDB 

SECBUF 


RMB 

162 

SECBUF 

• 

RMB 

256 

* SET 

* 

OF PROGRAM PROMPT AND ERROR MESSAGES 

Ml 

FCC 

*ENTER COMMAND: • 


FCB 

4 

M2 

FCC 

'ENTER FILE SPECIFICATION: ' 


FCB 

4 

M3 

FCC 

•ENTER RECORD SIZE : ' 


FCB 

4 

M4 

FCC 

•ENTER NO. OF RECORDS: • 


FCB 

4 

M5 

FCC 

•ENTER RECORD NUMBER: ' 


FCB 

4 

M6 

FCC 

'ENTER DATA: • 


FCB 

4 

M7 

FCC 

•BAD NUMBER' 


FCB 

$0D 


* 


* BEGIN PROGRAM CODE HERE 

START LDX #Ml PROMPT FOR COMMAND 

PRTMSG 

GTCMD GET COMMAND 

LDX DESCRA 
LDA A 0,X 

CMP A #'0 "OPEN"? 

BNE NEX1 NO 


* PROCESS "OPEN" COMMAND 

» 

LDX #M2 

PRTMSG 

GTCMD 

LDX DESCRA 
STX CUCHAR 
LDX #FCBLK 
FMTFCB 

TST FCBSTA,X 
BEQ 0PN2 

* 

ERROR LDX #FCBLK 
PRTERR 
BRA START 

• 

0PN2 JSR ROPEN 
BRA ERROR 


PROMPT FOR FILESPEC 

GET FILESPEC. 

BACK UP A TOKEN 

PUT FILESPEC INTO FCB 
ERROR? 

NO 


PRINT ERROR MESSAGE (IF ANY) 
GET NEW COMMAND 

OPEN FILE 

ERROR (IF ANY) AND LOOP 
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NEX1 CMP A #»C 
BNE NEX2 

» 

* PROCESS "CLOSE" COMMAND 

* 

LDX #FCBLK 
JSR RCLOSE 
BRA ERROR 

* 

NEX2 CMP A #'B 
BNE NEX3 

* PROCESS "BUILD" COMMAND 

* 

LDX #M2 

PRTMSG 

GTCMD 

LDX DESCRA 
STX CUCHAR 
LDX #FCBLK 
FMTFCB 

TST FCBSTA,X 
BNE ERROR 

• 

LDX #M3 
PRTMSG 
GTCMD 
LDA B RC 
CMP B #3 
BEQ BLD2 

* 

NUMERR LDX #M7 
PRTMSG 
JMP START 

« 

BLD2 LDA A VALUE 

LDA B VALUE+1 

LDX #FCBLK 

STA A FCBRSZ,X 

STA B FCBRSZ+1,X 

LDX #M4 

PRTMSG 

GTCMD 

LDA B RC 

CMP B #3 

BNE NUMERR 

* 

LDA A VALUE . 

LDA B VALUE+1 
LDX y/FCBLK 
STA A FCBRNM.X 


"CLOSE"? 

NO 


CLOSE FILE 

ERROR (IF ANY) AND LOOP 

"BUILD"? 

NO 

PROMPT FOR FILESPEC 

GET FILESPEC. 

BACK UP A TOKEN 

PUT FILESPEC INTO FCB 
ERROR? 

YES 

PROMPT FOR RECORD SIZE 

GET VALUE 
NUMERIC? 

YES 

PRINT "BAD NUMBER" MESSAGE 
TRY AGAIN 

PUT RECSIZ INTO FCB 

PROMPT FOR NO. OF RECORDS 

GET VALUE 
NUMERIC? 

NO 

PUT RECNUM INTO FCB 
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STA B FCBRNM+1,X 
JSR CREATE 
JMP ERROR 

NEX3 CMP A #'R 
BNE NEX4 

* 

« PROCESS "READ" COMMAND 

* 

RED1 LDX #BUFFER 
STX BUFPNT 

« 

RED2 LDX #FCBLK 
JSR RREAD 
TST FCBSTA,X 
BEQ RED3 

* 

JMP ERROR 

« 

RED3 LDX BUFPNT 
STA A 0,X 
CMP A #$OD 
BEQ RED4 

* 

INX 

STX BUFPNT 
CPX //BUFEND 
BNE RED2 

« 

LDX ^BUFFER 
PRTMSG 
BRA RED1 

* 

REDH LDX #BUFFER 
PRTMSG 
JMP START 

» 

NEX4 CMP A #’W 
BNE NEX5 

* PROCESS "WRITE" COMMAND 

LDX #M6 

PRTMSG 

GTCMD 

LDX DESCRA 
WRIT1 LDA A 0,X 
LDX #FCBLK 
JSR RWRITE 
TST FCBSTA,X 
BEQ WRIT2 


BUILD NEW FILE 

ERROR (IF ANY) AND LOOP 

"READ"? 

NO 


INIT. OUTPUT BUFFER POINTER 


READ BYTE FROM FILE 
ERROR? 

NO 

YES 

GET BUFFER POINTER 
STORE CHARACTER IN BUFFER 
CARRIAGE-RETURN? 

IF SO, FINISH UP 


MOVE BUFFER POINTER 
AT END OF BUFFER? 
NO, LOOP 


PRINT BUFFER CONTENTS 
LOOP FOR NEW BUFFER 


PRINT BUFFER CONTENTS 


"WRITE"? 

NO 


PROMPT FOR DATA 

GET DATA LINE 
POINT TO IT 
GET DATA BYTE 

WRITE DATA BYTE 
ERROR? 

NO 
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WRIT1A 

JMP ERROR 

YES 

ft 

WRIT2 

LDX DESCRA 



LDA A 0,X 

GET BYTE AGAIN 


CMP A #$0D 

C.R.? 

ft 

BEQ WRIT1A 

IF SO, DONE 


INX 

IF NOT, MOVE POINTER 

* 

STX DESCRA 

BRA WRIT1 

LOOP 

NEX5 

CMP A #»P 

"POSITION"? 

* 

BNE NEX6 

NO 

* PROCESS "POSITION" COMMAND 

* 


LDX #M5 

PROMPT FOR RECORD NUMBER 


PRTMSG 

GTCMD 

GET VALUE 


LDA B RC 

NUMERIC? 


CMP B #3 

BEQ POS1 

YES 

ft 

* 

JMP NUMERR 

NO 

POS1 

LDA A VALUE 



LDA B VALUE+1 

LDX #FCBLK 

PUT RECNUM INTO FCB 


STA A FCBRCD,X 

STA B FCBRCD+1,X 

JSR POSITION 

POSITION FILE 

ft 

JMP ERROR 

ERROR (IF ANY) AND LOOP 

NEX6 

CMP A #'E 

"EXPAND"? 


BNE NEX7 

NO 

ft 

* PROCESS "EXPAND" COMMAND 

• 



LDX #M4 

PROMPT FOR NO. OF RECORDS 


PRTMSG 

GTCMD 

GET VALUE 


LDA B RC 

NUMERIC? 

ft 

CMP B #3 

BEQ EXP1 

YES 

ft 

JMP NUMERR 

NO 

EXP1 

LDA A VALUE 



LDA B VALUE+1 

LDX #FCBLK 

PUT RECNUM INTO FCB 

94 

STA A FCBRCD,X 

STA B FCBRCD+1,X 
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JSR EXPAND ENLARGE FILE 

JMP ERROR ERROR (IF ANY) AND LOOP 

« 

NEX7 JMP START UNRECOGNIZED COMMAND 

« 

END 


RANDOM-ACCESS FILE SUPPORT FOR STRUBAL+ PROGRAMS 

All functions of the random-access file package are available to the 
STRUBAL+ programmer through procedures built into the random-access file- 
driver program supplied with the random-access package. This file-driver 
program includes all the support necessary for sequential file I/O plus 
all the additional random-file commands. Some of the random-file 
operations share the same keywords with the sequential operations. The 
shared keywords are: 

OPEN open a file for use 
CLOSE close a file after use 
READ read data from a file 
WRITE write data into a file 

The new set of keywords includes: 

BUILD create a new random-access file 

DELETE delete a file from the disk (random or sequential) 

ENLARGE add records to a random-access file 

LOCATE return the current file pointers of a random-access file 
PLACE position a random-access file to a given record 

This set of keywords provides support for all file manipulations under 
CP/68. 


The shared keywords READ and WRITE work the same way for sequential 
and random-access files. Data is moved sequentially starting with the 
current file position. The .EOF. and .ERR. functions are used in the same 
way with random-access files as they were with sequential files. The 
shared keyword CLOSE also works the same for both types of files in 
CP/68. The shared keyword OPEN has the same syntax for both types of 
files. If a random-access file is to be opened, append *;R* to the file 
specification instead of *;I* or *;0* used with sequential files. This 
identifies the file to be opened for random-access. 

Only files built for random access can be used as random-access 
files. Sequential files cannot be manipulated using random-access 
statements. A file with a filetype of 02 is a random-access file. Random- 
access files may be built under STRUBAL+ control using the BUILD 
procedure. They may be positioned to any desired record using the PLACE 
procedure. The current values of the file pointers may be obtained using 
the LOCATE procedure. Finally, records may be added to an existing 
random-access file through the use of the ENLARGE procedure. 
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BUILD procedure 


This procedure is used to create a new random-access file. Such a file is 
defined by its file specification (drive, name, and extension), a record 
count, and a record size. If FNAME is a string of characters containing a 
valid CP/68 file designation (which does not already exist on the disk), 
RECNO is an integer which contains the desired number of records to be in 
the file, and RECSIZ is an integer which contains the desired number of 
characters to be in each record, then the following procedure call will 
build the desired file. 


CALL BUILD(RFCB,FNAME,RECNO,RECSIZ) 

RFCB is the name of the user-supplied file-control block (FCB). The FCB 
must contain 426 bytes for systems whose sector size is 256, and 298 
bytes for systems whose sector size is 128 bytes. The BUILD procedure may 
take substantial time for a large file. The file is closed upon return 
from BUILD. 


ENLARGE procedure 

This procedure is used to add new records to an existing random- 
access file. The file must be already open before ENLARGE is called. 
ENLARGE requires the address of the file FCB and the desired number of 
records to be added as parameters. 

CALL ENLARGE(RFCB,RECNO) 

The file is closed upon return from ENLARGE. The ENLARGE procedure may 
take substantial time if many records are added to the file. 


LOCATE procedure 

This procedure returns the current file pointers of a random-access file. 
There are two pointers: the current record RECNO, and the current 
position within the record BYTNO. (These correspond to FCBRCD and 
FCBPOS.) LOCATE is called with the address of the file FCB as a 
parameter. 

CALL LOCATE(RFCB,RECNO,BYTNO) 

It returns two integer values containing the pointer contents. 


PLACE procedure 

This procedure moves the file pointers of a random-access file to a user- 
specified record. PLACE requires the address of the file FCB as a 
parameter, as well as an integer containing the desired record number. 
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CALL PLACE(RFCB,RECNO) 


PLACE always positions the file to the start of the desired record. 


USING RANDOM-ACCESS FILES IN STRUBAL+ 


The following STRUBAL+ example program illustrates the use of the random- 
access procedures to exercise random-access files. The example is similar 
in function to the assembly-language example shown earlier. 

« ILLUSTRATE USE OF RANDOM-ACCESS FILES THROUGH STRUBAL+ 

* ASSUME RANDOM-FILE PACKAGE AND DRIVERS LOADED 

« 

DSTRING DATA(80), RFCB (1*26), FNAME (30), CMD (10), TMP(1) 

INTEGER RECNO,RECSIZ,BYTNO 

* 

CALL INITIO 

* AVAILABLE COMMANDS ARE: 

* 

» BUILD, CLOSE, ENLARGE, OPEN, POSITION, READ, WRITE 

* 

START INPUT /,’ENTER COMMAND (B,C,E,0,P,R,W): »,$CMD 
XTRACT TMP=1,CMD 
STRING IF TMP .NE. 'O' THEN NEX1 

* PROCESS "OPEN" COMMAND HERE 

* 

INPUT /,'ENTER FILE SPECIFICATION: ',$FNAME 
STRING FNAME=FNAME,';R' 

OPEN (RFCB) FNAME 
GOTO START 

« 

NEX1 STRING IF TMP .NE. 'C' THEN NEX2 

« 

» PROCESS "CLOSE" COMMAND HERE 

« 

CLOSE (RFCB) 

GOTO START 

* 

NEX2 STRING IF TMP .NE. 'B* THEN NEX3 

« 

« PROCESS "BUILD" COMMAND HERE 

INPUT /,'ENTER FILE SPECIFICATION: »,*FNAME 
INPUT /,'ENTER NUMBER OF RECORDS: ',RECNO 
INPUT /,'ENTER RECORD SIZE: '.RECSIZ 
CALL BUILD(RFCB,FNAME,RECNO,RECSIZ) 

GOTO START 
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NEX3 STRING IF TMP .NE. »R» THEN NEX4 

* 

* PROCESS "READ" COMMAND HERE 

* 

CALL LOCATE(RFCB,RECNO,BYTNO) 

PRINT /,[6],'RECORDS,RECNO,' BYTEs',BYTNO 

* PRINT CURRENT POINTERS BEFORE READING 

READ (RFCB) $DATA 
PRINT /,[72],$DATA 
GOTO START 

* 

NEX4 STRING IF TMP .NE. 'W» THEN NEX5 

* 

* PROCESS "WRITE" COMMAND HERE 

* 

INPUT /,'ENTER DATA: ',$DATA 
WRITE (RFCB) $DATA 
GOTO START 

NEX5 STRING IF TMP .NE. 'P* THEN NEX6 

* 

* PROCESS "POSITION" COMMAND HERE 

* 

INPUT /,'ENTER RECORD NUMBER: ',RECNO 
CALL PLACE(RFCB,RECNO) 

GOTO START 

* 

NEX6 STRING IF TMP .NE. 'E' THEN START 

* 

* PROCESS "ENLARGE" COMMAND HERE 

* 

INPUT /,'ENTER NUMBER OF RECORDS: ',RECNO 
CALL ENLARGE(RFCB,RECNO) 

GOTO START 

* 

END 


DELETING A FILE USING STRUBAL+ 

One additional procedure is contained in the new file driver 
program; this procedure allows STRUBAL+ programs to delete files from 
disk. Only unambiguous names can be used; no wildcards are allowed. The 
DELETE procedure requires an FCB in the user program. This FCB can be 
sized either for sequential files or random-access files. The file 
specification is passed as a string to the procedure. 

CALL DELETE(RFCB,DNAME) 

Care should be taken with this procedure, as once a file is deleted 
it is lost. There will be no prompting, unlike the DELETE command under 
CP/68. 
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Part 6 


MODIFICATIONS FOR DISK HARDWARE DIFFERENCES 

****»*•»•*•***«**«•*«•«•«*«•**»•»«**««*•*«* 

CP /68 can be tailored for a wide variety of disk configurations. 
This section will describe the places which must be modified for most 
common hardware setups. There are three parameters which describe a disk 
to CP/ 68 : 

SECSIZ the number of bytes in a sector (128 assumed) 

TRKSIZ the number of sectors in a track (18 assumed) 

DSKSIZ the number of tracks on a disk (35 assumed) 

In addition, CP /68 checks the number of drives. From 1 to 4 drives 

may be used. (CP /68 as described here assumes four drives.) More than 
four drives can be used if more space is allocated to the free-space 
pointer table (FRETAB) in the base-page. Two bytes are needed for each 
drive added. 


SECSIZ 

This parameter is the most important one, as it affects the buffer sizes 
for the sector buffers in the system. Sector buffers appear in: 

CLI- SAVFCB, SYSFCB, SUBFCB 

BOOT- BUFFER 

DELETE- SYSFCB 

INIT- FCBSPC 

LINK- SYSFCB 

PIP- INFCB, OUTFCB 

SECURITY- SYSFCB 

RNDFILE- RNDFCB 

All sector buffers are sized for 128 bytes as shown. They could be 
enlarged to 256 bytes if necessary. Larger sectors would require 
extensive modification since byte counts are kept in 8 -bit locations 
throughout CP/ 68 . 

SECSIZ also is used as a parameter in CP /68 to allow addressing of 
elements of a sector or to compute constants based on the sector size. 
Use of SECSIZ as a parameter appears in: 

CLI, DREAD, Sequential File I/O, BOOT, INITIALIZE, LINK and RNDFILE 


(c) Hemenway Associates, Inc, 1979 
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TRKSIZ 


This parameter is used in the following routines: 

CLI- in subroutine SEMPTY 

DREAD- in subroutine GETDR 

INIT- 

PIP- in subroutine DTDCPY 

FORMAT- 

The use of TRKSIZ in INITIALIZE includes the length of the sector- 
interleave table TBL. There must be a table entry for each sector on a 
disk track. 


DSKSIZ 

This parameter is used in the following routines: 

INIT- 

PIP- in subroutine DTDCPY 

FORMAT- 

CP/68 assumes that all disks have the same DSKSIZ. 

Number of Drives in System 

This parameter appears in the following routines: 

CLI- at WARM3 (to initialize FRETAB) 
in subroutine INICMD 
in subroutine DIRCMD 
in subroutine FMTFCB 

SFIO- (mask off low 2 bits of drive number to access FRETAB) 

DELETE- 

INITIALIZE- 

LINK- 

PIP- 

SECURITY- 

FORMAT- 

RNDFILE- (mask off low 2 bits of drive number to access FRETAB) 

In all cases except SFIO and RNDFILE, the checks on drive number are 
used for error-detection only. 
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DISK HANDLING SOFTWARE 


Any disk operating system like CP/68 must be modified for use on 
different hardware. The hardware-specific code is localized in the 
DRIVERS, BOOT, and FORMAT. The DRIVERS require initialize, sector-read, 
and sector-write capabilities for multiple drives. BOOT requires only 
initialize and sector-read from drive 0. FORMAT requires track-seek and 
track-write capability for multiple drives. Drivers for several common 
disk configurations are given here. They each perform the same functions- 
-only one is needed for CP/68. 


MODIFICATIONS FOR VARIOUS SYSTEM MONITOR ROMS 

CP/68 makes no use of system monitor routines during its execution. As a 

result, any of the current "-BUG" monitors can be used with it. BIOS 

contains the addressing for the various I/O devices (EQTAB), which may 
need changing for different addressing of I/O devices. BIOS also contains 
an error trap for CP/68 calls (SWIs) that have an invalid function code. 
This trap should vector to the normal breakpoint entry in the monitor 
ROM. This vector is directed to El 13 hex in SWIHDR. CLI also contains a 
vector to the monitor in its command table (CMDTAB). The EXIT command is 
vectored to the warm-start entry of the monitor ROM (the version shown 
goes to E0E3 hex). The BOOT transient contains an error trap which is 
jumped to in case of disk errors during boot. This vector is shown as 
El 13 hex (like the one in BIOS). 

One other modification will be necessary to use CP/68—point the SWI 
vector of the system to the SWIHDR entry. Some means must be found to 
force SWIs to be processed by SWIHDR. The BOOT process must set up the 
SWI vector, or else it must be set by code at the COLDST entry in CLI. 


(c) Hemenway Associates, Inc, 1979 
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Part 7 


Software Listings 

******** ******** 

Resident 

BIOS.103 

CLI.117 

DIRECTORY.140 

SFIO.142 

ICOM driver.150 

Transients 

ASSIGN.153 

BOOT.156 

DELETE.158 

INITIALIZE.162 

LINK.165 

PIP.168 

SECURITY.184 

SET.187 

STATUS.189 

RANDOM.191 

Hex dump of resident code.206 

Load map.208 

Hex dump of transients.209 

Southwest Technical Products drivers.211 

BOOT.215 

INITIALIZE.218 

FORMATTER.221 

Smoke Signal Broadcasting drivers.224 

BOOT.227 

INITIALIZE.229 

FORMATTER.232 

Percom Data Company 

Single-sector read and write.236 

INITIALIZE.238 

BOOT.241 
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